View source for MMPM/2 Device Driver Reference

By [[IBM]]

== MMPM/2 Device Driver Reference ==

'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''

=== About This Book ===
The ''MMPM/2 Device Driver Reference for OS/2'' is for subsystem developers who want to write their own physical device drivers (and associated virtual device drivers) to support audio and video adapters in the Multimedia Presentation Manager/2 system.

'''Note:''' Multimedia Presentation Manager/2 (MMPM/2) is also referred to as "OS/2 Multimedia".

The IBM Developer Connection Device Driver Kit for OS/2 (DDK) provides PDD and VDD source code that serves as a template that can be modified easily to meet your hardware requirements. Tools to test your device drivers are also available.

=== Related Information ===
You should be familiar with the IBM Developer's Toolkit for OS/2. Related OS/2 and OS/2 multimedia technical information includes:

''OS/2 Physical Device Driver Reference'' Defines what a physical device driver is, and how it operates. It also describes the types of physical device drivers, their interfaces, and available system services.

An online version of this book is provided in this package.

''OS/2 Virtual Device Driver Reference'' Defines what a virtual device driver is, how it operates, and when to use one. It also describes the types of virtual device drivers, their interfaces, and available kernel services.

An online version of this book is provided in this package.

''OS/2 Multimedia Technical Library''

Online versions of the following books are provided with the OS/2 Developer's Toolkit.

''OS/2 Multimedia Subsystem Programming Guide'' Provides guidelines for developing multimedia subsystems. Each subsystem component is described in detail in individual chapters. Models are used to complement the information provided by component sample program templates.

''OS/2 Multimedia Application Programming Guide'' Provides advisory information on application interfaces to help you select and implement functions for your OS/2 multimedia applications. Code examples from fully documented sample programs accompany the descriptions of the functions.

''OS/2 Multimedia Programming Reference'' Provides detailed information on multimedia functions, messages, and data structures to enable you to write code for your multimedia application programs and subsystems.

=== Using the Online Reference ===
Before you begin to use this reference, it would be helpful to understand how you can:
* Expand the Contents window to see all available topics
* Obtain additional information for a highlighted word or phrase
* Use action bar choices

====How to Use the Contents====
When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign (+) indicates that additional topics are available.

To expand the Contents if you are using a mouse, click on the plus sign. If you are using a keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus key (+).

To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press Enter).

====How to Obtain Additional Information====
After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words in the following paragraph are highlighted in green letters. These are called "hypertext terms". If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word and then press Enter. Additional information will appear in a window.

To return to the window you were viewing before you selected a hypertext term, press Esc.

====How to Use Action Bar Choices====
Several choices are available for managing information presented in the online MMPM/2 Device Driver Reference. There are three pull-down menus on the action bar: the '''Services''' menu, the '''Options''' menu, and the '''Help''' menu.

The actions that are selectable from the '''Services''' menu operate in the active window currently displayed on the screen. These actions include the following:

Bookmark Sets a place holder so you can retrieve information of interest to you.

When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty.

To set a bookmark, do the following:
#Select a topic from the Contents.
#When that topic appears, choose the '''Bookmark''' option from the '''Services''' menu.
#If you want to change the name used for the bookmark, type the new name in the field.
#Select the '''Place''' radio button (or press the Up or Down Arrow key to select it).
#Select '''OK'''. The bookmark is then added to the bookmark list.

Search Finds occurrences of a word or phrase in the current topic, selected topics, or all topics.

You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list.

To search for a word or phrase in all topics, do the following:
#Choose the '''Search''' option from the '''Services''' pull-down.
#Type the word or words to be searched.
#Select '''All sections'''.
#Select '''Search''' to begin the search.
#The list of topics where the word or phrase appears is displayed.

;Print
:Prints one or more topics. You can also print a set of topics by first marking the topics in the Contents list.

You can print one or more topics. You can also print a set of topics by first marking the topics on the Contents list.

To print the document Contents list, do the following:
#Select '''Print''' from the '''Services''' menu.
#Select '''Contents'''.
#Select '''Print'''.
#The Contents list is printed on your printer.

;Copy
:Copies a topic you are viewing to a file you can edit.

You can copy a topic you are viewing into a temporary file named "TEXT.TMP". You can later edit that file by using an editor such as the System Editor.

To copy a topic, do the following:
#Expand the Contents list and select a topic.
#When the topic appears, select '''Copy to file''' from the '''Services''' menu.

The system copies the text pertaining to that topic into the temporary TEXT.TMP file.

For information on any of the other choices in the '''Services''' menu, highlight the choice and press the F1 key.

;Options 
:Changes the way the Contents list is displayed.

You can control the appearance of the Contents list.

To expand the Contents and show all levels for all topics, select '''Expand all''' from the '''Options''' menu.

For information on any of the other choices in the '''Options''' menu, highlight the choice and press the F1 key.

=== What's New ===
* Discussion of and pointers to the PAS16 audio sample have been removed.
* Pointers to the new object-oriented audio driver sample, TROPEZ.SYS have been included.
* References to the AUDIOVDD.SYS virtual driver have been removed. The VBSAUDIO.SYS driver serves as its replacement.

For information on any items discussed in this reference that have been added to OS/2 (beginning with Warp) and their compatibility with different versions of OS/2, see ''OS/2 Version Compatibility Considerations''.

=== Assistance ===
Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DDSC BBS, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:
: Internet: ibmsdp@vnet.ibm.com
: US/Canada: 800-627-8363
: International: 770-835-9902
: International Fax: 770-835-9444

=== Ordering Information ===
In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.

*The Physical Device Driver Reference
*The Storage Device Driver Reference
*The Input/Output Device Driver Reference
*The Pen for OS/2 Device Driver Reference
*The Virtual Device Driver Reference
*The Presentation Device Driver Reference
*The Display Device Driver Reference
*The Printer Device Driver Reference
*The Graphics Adapter Device Driver Reference
*The MMPM/2 Device Driver Reference (Multimedia)

To order the DDK call:
{|class="wikitable"
||U.S.A.: ||1-800-633-8266 || 
|-
|Canada: ||1-800-561-5293 || 
|-
|When calling from Europe, the Middle East, or Africa, the number depends on the language you use to place the order:|| English ||(+45) 48101500       
|-
|| || French ||(+45) 48101200
|-
|| || Italian ||(+45) 48101600
|-
|| || German ||(+45) 48101000
|-
|| || Spanish ||(+45) 48101100
|-
|| || Dutch ||(+45) 48101400
|-
|| || Danish ||(+45) 48101300
|-
|| || Finish ||(+45) 48101650
|-
|| || Swedish ||(+45) 48101150
|-
|| || Norwegian ||(+45) 48101250
|-
|| || FAX ||(+45) 48142207
|-
|When ordering from Latin America or South America, the number depends on the country from which you are calling: || 
* Bolivia ||    02-35 1840
| ||* Columbia           |   01-257-0111
|  |* Dominican Republic |      566-5161
|   |* El Salvador        |    02-98 5011
|    |* Honduras           |       32-2319
|       |* Paraguay           |   021-444 094
|            |* Urugruay           |    02-923 617
|* Chile              |   02-633-4400
|* Costa Rica         |      223-6222
|                    |* Ecuador            |    02-56 5100
|                    |* Guatemala          |    02-31 5859
|                    |* Panama             |    02-639 977
|                    |* Peru               |   014-36 6345
|                    |* Venezuela          |   02-908-8901
|                    |* Argentina          |   01-313-0014
|-
|To order from Asia/ |* All except Japan   |(61) 2-354-7684
|Pacific:            |* Japan              |(81) 3-3495-2045(Fax)
|                    |                     |Fax request to:
|                    |                     |DAP-J, IBM Japan
|-
|To order from SE    |(021) 800-6120(Voice)|
|Brazil:             |(021) 800-6936(Fax)  |
|-
|To order from       |* Mexico City        |627-2444
|Mexico:             |* Country            |91-800-00639
|}

=== Adding Support for Audio and Video Adapters ===
This DDK enables adding audio and video adapter support to the Multimedia Presentation Manager/2 (MMPM/2) audio and video subsystems without having to write a separate installation DLL for each adapter.

Adapters are added to the appropriate MMPM/2 subsystem by:
*Specifying parameters in a ''resource file (.RC)''. The resource file is compiled to create the resource DLL.

*Modifying control files that tell MINSTALL how to install your adapter.
*Modifying a help file that displays help information to users when they are installing your adapter.

This process is shown in the following illustration for a video adapter. [Artwork not shown]

For additional information about adding support for an audio adapter, see [[00007.htm|Audio Adapter Installation]]or for adding support for a video adapter, see [[00022.htm|Video Adapter Installation]].





=== Audio Adapter Installation ===

MMPM/2 allows installation of device drivers developed for audio adapters into the MMPM/2 audio subsystem. MMPM/2 can then use the audio adapter to play and record digital audio files. It can also play, but not record, MIDI files.

This DDK provides a generic installation program that performs the following functions:

�Asks the user for any information needed to install your adapter, such as the interrupt level.

�Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements.

�Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver.

�Copies the files needed by your adapter, such as device drivers.

The following steps provide an overview of how to use the generic audio installation program to install a device driver into the MMPM/2 audio subsystem. The \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory provides the generic audio installation sample files. For more information about the AUDINST files, see [[00008.htm|Source Code]]. More detailed information about each step is provided in the following sections.

To add an audio adapter to the MMPM/2 audio subsystem, follow these steps:

1.Create an OS/2 device driver for the audio adapter.

For information on creating an OS/2 device driver, refer to [[00035.htm|Audio Physical Device Driver Template]].

2.Write a Vendor-Specific Driver Resource File.

This file is an audio resource file that describes your audio device to MMPM/2.

For more information, see [[00010.htm|Step 2. Writing a Vendor-Specific Driver]].

3.Modify the CARDINFO.RC file.

This file contains specific information about the adapter. MMPM/2 uses this information to interface with the adapter.

For more information, see [[00012.htm|Step 3. Modifying the CARDINFO.RC File]].

4.If necessary, create a DLL to perform actions not provided by this generic audio installation program.

This step is not necessary, unless you want to perform some action that is not provided by the generic audio installation program.

For more information, see [[00014.htm|Step 4. Creating an Audio Installation DLL]].

5.Modify the AUDHELP.ITL file.

This file contains information that is presented to the user when installing your adapter.

For more information, see [[00015.htm|Step 5. Modifying the AUDHELP.ITL File]].

6.Run the MAKEFILE.

This file compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles AUDHELP.ITL into a help file called AUDHELP.HLP.

For more information, see [[00016.htm|Step 6. Running the MAKEFILE]].

7.Modify the CONTROL.SCR file.

This file is the control file used by MINSTALL to determine what subsystems and devices a user can install.

For more information, see [[00017.htm|Step 7. Modifying the CONTROL.SCR File]].

8.Modify the AUDFILES.SCR file.

This file lists the files the adapter uses. It tells MINSTALL which files need to be copied and into which subdirectories to place them.

For more information, see [[00018.htm|Step 8. Modifying the AUDFILES.SCR File]].

9.If necessary, create a MIDI map.

This step is not necessary if the adapter uses the general MIDI specifications.

For more information, see [[00019.htm|Step 9. Creating a MIDI Map]].

10.Create an installation diskette.

This diskette must contain all the files necessary to install the adapter into the MMPM/2 audio subsystem using MINSTALL.

For more information, see [[00020.htm|Step 10. Creating the Installation Diskette]].

11.Install your adapter using MINSTALL.

For more information, see [[00021.htm|Step 11. Using MINSTALL to Install Your Adapter]].





=== Source Code ===

The \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory provides the generic audio installation sample files. These sample files illustrate how to install an audio device driver into the MMPM/2 audio subsystem. The sample files include:

<pre class="western">/-------------------------------------------------------------\
|Source File              |Description                        |
|-------------------------+-----------------------------------|
|MAKEFILE                 |Creates the resource DLL containing|
|                         |the audio adapter information by   |
|                         |compiling the CARDINFO.RC file into|
|                         |the CARDINFO.DLL file. This file   |
|                         |also compiles the AUDHELP.ITL file |
|                         |into the AUDHELP.HLP help file.    |
|-------------------------+-----------------------------------|
|CARDINFO.RC              |Supplies information about the     |
|                         |audio adapter.                     |
|-------------------------+-----------------------------------|
|MIDIMAP.RC               |Contains the sample MIDI map table.|
|-------------------------+-----------------------------------|
|RCSTUB.C                 |Stub 'C' file for compiling        |
|                         |CARDINFO.RC.                       |
|-------------------------+-----------------------------------|
|AUDHELP.ITL              |Contains the help information.     |
|-------------------------+-----------------------------------|
|CONTROL.SCR              |Contains the control information   |
|                         |used by MINSTALL to install the    |
|                         |audio adapter.                     |
|-------------------------+-----------------------------------|
|AUDFILES.SCR             |Lists the files to be copied by    |
|                         |MINSTALL. MINSTALL also copies this|
|                         |file.                              |
|-------------------------+-----------------------------------|
|MIDIMAP.SCR              |Contains the INI change control    |
|                         |file used by MINSTALL to install a |
|                         |MIDI map table.                    |
|-------------------------+-----------------------------------|
|GENIN.DLL                |Is the generic installation program|
|                         |that installs your adapter.        |
|-------------------------+-----------------------------------|
|GENINMRI.DLL             |Contains the text used be GENIN.DLL|
\-------------------------------------------------------------/</pre>
'''Note:'''Before modifying any of these files, make sure you have a backup copy.





=== Step 1. Creating an OS/2 Device Driver for an Audio Adapter ===

For information on creating an OS/2 device driver, refer to [[00035.htm|Audio Physical Device Driver Template]].





=== Step 2. Writing a Vendor-Specific Driver ===

The vendor-specific driver (VSD) resource file describes your audio device to MMPM/2. When audio services are requested, the Media Device Manager (MDM ) communicates with the amplifier-mixer (ampmix) device. Then, the ampmix device is opened, and it loads the VSD resource DLL and transfers adapter information into a memory buffer. If a user requests a particular mode (or audio setting), the VSD looks up that mode to determine the device characteristics and reports the specific information to the MDM. This process is shown in the following illustration:

[Artwork not shown]

You can reduce the amount of code required to add a device to MMPM/2 by using a VSD resource file. This file enables you to supply only one DLL for all the devices being added to MMPM/2.

To add a new audio device to the MMPM/2 audio subsystem, you must supply a device driver and a VSD resource file. Both are installed using the generic audio installation program. For more information, see [[00007.htm|Audio Adapter Installation]].

An example VSD resource file (SAMPLE.RC) is in the \MMOS2\MMTOOLKT\SAMPLES\ VSDRC subdirectory. When you use the generic audio installation program, you must specify the following parameters in the audio ampmixer's device- specific parameters:

RESOURCEDLL= Specifies the name of the DLL that contains the audio resource description. The resource example in the Toolkit contains a DLL named SAMPLE.DLL and creates the following line in the MMPM2.INI file:

<pre class="western">RESOURCEDLL=SAMPLE</pre>
'''Note:'''Do not specify the .DLL extension.

RCID= Indicates which adapter in the VSD resource file is used for audio support. Resource DLLs can contain descriptions for multiple adapters. The sample resource file (\MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC) contains a description of two audio adapters, the ProAudio Spectrum (indicated by RCID =1) and the Sound Blaster Pro (indicated by RCID=2).





=== Resource File Layout ===

The following is the format of the vendor-specific driver (VSD) resource file:

<pre class="western">BEGIN
RCDATA  &lt;Device Number&gt;
&lt;Device Name&gt;,
&lt;Device ID&gt;, &lt;Reserved1&gt;,
&lt;Reserved2&gt;,
&lt;Number of Datatype Rows&gt;,
&lt;Datatype Row&gt;
END</pre>
The following list describes the VSD resource file format parameters:

RCDATA Indicates the beginning of the resource file for each audio adapter. For example, in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC file, this parameter is (indicated in red):

<pre class="western">RCDATA PAS_16</pre>
Device Number Describes the offset in the resource file used to describe the device. This parameter is usually the name of the adapter. For example, in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">RCDATA PAS_16</pre>
and for the Creative Labs Sound Blaster Pro adapter it is:

<pre class="western">RCDATA SB_PRO</pre>
Each device number in the resource file must be unique. These numbers are determined by the manufacturer. The defines for the device numbers that are valid in this field are in the SAMPLE.H file.

This field must be a ULONG.

Device Name Indicates the device name. This parameter must be the first item in the table because it is used by the amplifier-mixer to return product information. This string must be an ASCII string. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is:

<pre class="western">&quot;Media Vision Pro Audio Spectrum&quot;</pre>
and for the Creative Labs Sound Blaster Pro adapter it is:

<pre class="western">&quot;Creative Labs Sound Blaster Pro&quot;</pre>
Device ID Indicates which device the system is using. It is the same as the device ID returned from the AUDIO_INIT IOCtl. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is ( indicated in red):

<pre class="western">PAS16, 0,</pre>
and for the Creative Labs Sound Blaster Pro adapter it is (indicated in red ):

<pre class="western">SOUND_BLASTER, 0,</pre>
This field must be a USHORT.

'''Note:'''Because the Device ID in not explicitly defined to be a LONG, the resource compiler assumes this field is a USHORT.

Reserved1 This parameter is reserved and should be set to 0. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">PAS16, 0, 0,</pre>
This field must be a USHORT.

Reserved2 This parameter is reserved and should be set to 0. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">PAS16, 0, 0,</pre>
This field must be a USHORT.

Number of Data Type Rows Indicates the number of data type rows. A data type row is defined below.

Some parameters in the data type row can be duplicated, however, all rows must be unique. For example, the Bits Per Sample parameter is repeated often, but the rows are unique.

In the SAMPLE.RC file, the Media Vision ProAudio Spectrum adapter has 17 unique combinations of parameters such as Samples Per Second, Bits Per Sample, and Channels (these fields are described in the following parameters). Therefore, the value of this field is:

<pre class="western">17L</pre>
and the Creative Labs Sound Blaster Pro adapter has 11 unique row descriptions. Therefore, the value of this field is:

<pre class="western">11L</pre>
This field must be a ULONG.

Data type Row A data type row describes the specific capabilities of each of audio device and consists of a combination of the following parameters:

�RIFF Data Type <br />�RIFF Data Subtype <br />�Samples per Second <br />�Bits per Sample <br />�Channels <br />�Sampling Descriptions <br />�Play Resource Class <br />�Play Resource Units Used <br />�Record Resource Class <br />�Record Resource Units Used

RIFF Data Type Indicates a RIFF defined data type indicated in OS2MEDEF.H. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
For additional information, see the ''OS/2 Multimedia Programming Reference''. These are the same subtypes used in the streaming subsystem.

This field must be a ULONG.

RIFF Data Subtype Indicates the RIFF subtypes for a given data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
For additional information, see the ''OS/2 Multimedia Programming Reference''. These are the same subtypes used in the streaming subsystem.

Samples Per Second Indicates the sampling rate supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
This field must be a USHORT.

Bits Per Sample Indicates the bits per sample supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
This field must be a USHORT.

Channels Indicates the channels supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
This field must be a USHORT.

Sampling Descriptions Describes the sampling rates. If the current data type row supports a specific sampling rate (for example, the device only supports one specific rate), the STATIC_RATE flag should be specified. For example, the M-Audio adapter can play only one specific sampling rate, so the STATIC_FLAG is specified (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16   8000,  16,  1, STATIC_RATE,      PCM_CLASS,  1, 0,         0,</pre>
If a range of sampling rates are supported (for example, the device can play any rate between 2 kHz and 48 kHz), the lowest sampling rate in the range should contain the BEGIN_CONTINUOUS flag and highest sampling rate should be specified in one of the following rows with the END_CONTINUOUS flag. Intermediate sampling rates should also contain the BEGIN_CONTINUOUS flag. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter indicates support for rates between 2 kHz and 48 kHz (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,
DATATYPE_WAVEFORM,   WAVE_FORMAT_1M16,  11025, 16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,
DATATYPE_WAVEFORM,   WAVE_FORMAT_2M16,  22050, 16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,
DATATYPE_WAVEFORM,   WAVE_FORMAT_4M16,  48000, 16,  1, END_CONTINUOUS,   PCM_CLASS,  1, PCM_CLASS, 1,</pre>
Notice that BEGIN_CONTINUOUS is used with the first sampling rate of 2000 and that END_CONTINUOUS ends the sampling rate at 48000. For additional information, see the ''OS/2 Multimedia Subsystem Programming Guide''.

This field must be a ULONG.

Play Resource Class Indicates the class for the data type defined in this row. For example, this parameter indicates that when a particular data type is defined, the data type falls under this particular class. This parameter matches a class defined for the amplifier-mixer (ampmix) device in the MMPM2.INI file and is determined by the manufacturer. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
This parameter is defined in the SAMPLE.H file. This field must be a USHORT .

Play Resource Units Used Indicates the number of resource units this RIFF data type (or class) consumes. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
The Media Vision ProAudio Spectrum adapter only supports one instance at a time playing PCM, so the total resources for the class is 1. When this parameter specifies 1 for the Data type row, MDM assures that not more than one instance plays PCM at any one time. For additional information, see the ''OS/2 Multimedia Subsystem Programming Guide''.

This field must be a USHORT.

Record Resource Class Indicates the class for the RIFF data type in record mode. This parameter matches the class defined in the MMPM2.INI file and is determined by the manufacturer. If this value is nonzero, the amplifier- mixer assumes that recording is possible for this data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>
If the class contains a zero, it is assumed that recording is not possible. For example, a device might not be able to record mono, PCM, 44 kHz data. Therefore, a 0 is entered in the record class (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16, 44000,   8,  1,   END_CONTINUOUS, PCM_CLASS,  1, 0,         1,</pre>
This parameter also indicates that when a particular data type is defined, the data type falls under this particular class. The Media Vision ProAudio Spectrum adapter supports only one instance at a time when recording PCM, so the total resources for the class is 1. When this parameter specifies 1 for the data type, MDM assures that the device does not exceed this number of units.

This field must be a USHORT.

Record Resource Units Used Indicates the number of resources this RIFF data type consumes in record mode (USHORT). For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

<pre class="western">DATATYPE_WAVEFORM,   WAVE_FORMAT_8M16,  2000,  16,  1, BEGIN_CONTINUOUS, PCM_CLASS,  1, PCM_CLASS, 1,</pre>






=== Step 3. Modifying the CARDINFO.RC File ===

The CARDINFO.RC file is located in the \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory. Modify this file so that it contains information relevant to your audio adapter. MMPM/2 uses this information to interface with your adapter.

'''Notes:'''

1.The lines in this file that contain RCDATA, BEGIN, and END identify the beginning and ending of specific pieces of data. Do not change these lines.

2.If more than one adapter is added, increment each RCDATA number by 10 for each additional adapter. For example, the first adapter uses RCDATA 10 through RCDATA 19, the second adapter uses RCDATA 20 through RCDATA 29, and so forth.

3.If the audio adapter does not have a value corresponding to one of the CARDINFO.RC file parameters, use a null string &quot;/0&quot; in the parameter.

The CARDINFO.RC parameters are:

RCDATA 1 Indicates the number of adapters described in this CARDINFO.RC file. In most cases, this is 1. To install more than one type of audio adapter, place that number in this parameter.

For example, in the CARDINFO.RC file, the ProAudio Spectrum adapter is:

<pre class="western">RCDATA 1
BEGIN
   &quot;1&quot;           /* Number of adapters in this rc file */
END</pre>
RCDATA 10 Contains two parameters, the ID number and the type of audio adapter. The ID number is used in the CONTROL.SCR file that you modify in Step 7. The ID number can be any number. However, it must match the ''ssdllinputparms''keyword in the CONTROL.SCR file. For the type of adapter, use &quot;audiovdd&quot; if the adapter uses the IBM AUDIOVDD.SYS device driver. If the adapter does not use this driver, put &quot;audio&quot; in this field.

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

<pre class="western">RCDATA 10
BEGIN
   &quot;26&quot;,            /* ID number of this adapter             */
   &quot;audiovdd&quot;       /* Type of adapter - use audiovdd if     */
                    /* you use the IBM audiovdd.sys driver   */
END</pre>
For more information, see [[00035.htm|Audio Physical Device Driver Template]].

RCDATA 11 Contains parameters that indicate:

�The maximum number of this type of audio adapter that can be installed at one time. The maximum is six adapters.

�The name of the help file that describes the audio adapter. This name defaults to AUDHELP.HLP if the MAKEFILE provided to create the help file is used.

�The name of the audio-adapter-specific DLL you wrote to perform functions not provided by this generic audio installation program. This DLL is described in [[00014.htm|Step 4. Creating an Audio Installation DLL]]. If you did not write a DLL, specify &quot;\0&quot;.

�The name of the audio-adapter-specific DLL entry point into the DLL in the previous field. If you did not write a DLL, specify &quot;\0&quot;.

�The number of CONFIG.SYS lines to add to the user's CONFIG.SYS file to support the audio adapter. The maximum is six lines.

'''Note:'''Do not count the AUDIOVDD.SYS line.

�The CONFIG.SYS line format of the lines added to the user's CONFIG.SYS file (except for the AUDIOVDD.SYS line). Tokens in this line are replaced with the appropriate values at runtime. The following list describes the tokens and their data substitutions:

*PATH* Indicates the path where MMPM/2 is installed (for example, c:\MMOS2) .

*ORD* Indicates the device ordinal of this adapter.

*SEQ* Indicates the sequential number of this adapter. For example, if the user installs two IBM audio adapters, the first will have a number of 1 and the second a number of 2.

*PDD* Indicates the PDDName of this adapter.

*VAL* Indicates the values that the user gives when prompted by the installation program. You can have more than one of these tokens if the user is asked for more than one item.

'''Note:'''Later in the CARDINFO.RC file, you specify which questions the installation program should ask.

*SPEC* Indicates special values passed from your adapter-specific DLL.

For example, the line in the sample CARDINFO.RC file is:

&quot;DEVICE=*PATH*\\MVPRODD.SYS /I*VAL* /D*VAL* /N:*PDD*&quot;

After the real values are substituted, the CONFIG.SYS line is similar to:

DEVICE=C:\MMOS2\MVPRODD.SYS /I5 /D12 /N:PAS161$

�The number of drivers to install into the MMPM/2 system. For an audio adapter, this would normally be three because most audio adapters install a Waveform, Audio Sequencer, and Audio Ampmixer driver. The maximum is six drivers.

�The name of the adapter as it is displayed to the user.

�The version number of the device driver.

�The physical device driver name (PDDName) used to identify the device driver. The sequential number of the adapter and a &quot;$&quot; is added to this name to form the final PDDName. For example, if the user installs two ProAudio Spectrum 16 adapters, the PDDNames are PAS161$ and PAS162$.

�The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'.

�The name of the VSD command table used by the drivers. In most cases this is blank.

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

<pre class="western">RCDATA 11
BEGIN
   &quot;1&quot;,                        /* Max number of adapters (2 chars)           */
   &quot;audhelp.HLP&quot;,              /* Helpfile name (19 chars)                   */
   &quot;\0&quot;,                       /* Adapter specific dll name (19 chars)       */
   &quot;\0&quot;,                       /* Adapter specific dll entry point (39 chars)*/

   /**** Data for CONFIG.SYS **/
   &quot;1&quot;,                        /* Number of CONFIG.SYS lines (1 char)        */
   &quot;DEVICE=*PATH*\\MVPRODD.SYS /I*VAL* /D*VAL* /N:*PDD*&quot;
                               /* CONFIG.SYS Line 1                          */
                               /* (255 chars after token substitution)       */

   /**** Data for INI File ****/
   &quot;3&quot;,                        /* Number of Drivers to Install (1 char)      */
   &quot;Pro AudioSpectrum 16&quot;,     /* Product name (39 chars)                    */
   &quot;1.0&quot;                       /* Version of the adapter's software (5 chars)*/
   &quot;PAS16&quot;,                    /* PDD Name  (6 chars)                        */
   &quot;MDM&quot;,                      /* MCD table name (19 chars)                  */
   &quot;\0&quot;                        /* VSD table name (19 chars)                  */
END</pre>
RCDATA 12 This group of parameters is repeated for each driver you want to install. The repeated groups start with RCDATA 13, RCDATA 14, and so forth. ) These parameters indicate:

�The InstallName of this driver. This must be a unique name. Consider using a name that is a combination of a company name, device type, and device model. The sequential number of this adapter is added to the name (for example, IBMWAVEPAS1601).

�The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

�The numeric device flag of this driver. Specifies the LONG INT with the flags set. This determines whether or not the device is controllable. The device flags are defined in the MCIOS2.H file located in the \MMOS2\ MMTOOLKT\H subdirectory.

�The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD &quot;AUDIOMCD.&quot;

�The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD &quot;AUDIOIF.&quot;

�The numeric share type. Specifies an encoding of the valid types of sharing supported. These codes are defined in the MMDRVOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

�The name to be given to this driver's resources. Specifies a unique name for the management of the driver resources. The sequential number of the adapter is added to this name so that resources of different drivers are not mixed. If you have more than one driver, be sure to use a different resource name for each driver. For more information, see [[00034.htm|Resource Units and Classes]].

�The number of resource units supported by this driver. For more information, see [[00034.htm|Resource Units and Classes]].

�The number of resource classes supported by this driver. The maximum is nine resource classes. These classes are listed in the next field. For more information, see [[00034.htm|Resource Units and Classes]].

�The resource classes. For more information, see [[00034.htm|Resource Units and Classes]] .

�The number of valid combinations of resource classes. The maximum is 81 combinations. For more information, see [[00034.htm|Resource Units and Classes]].

�The valid resource class combinations. Resource class combinations are always listed in pairs. For example, if a class 1 can combine with a class 2, then class 2 can combine with class 1.

For more information, see [[00034.htm|Resource Units and Classes]].

�The number of connectors. These are listed in the next field. The maximum is 10 connectors. Each implementation of a media driver defines the paths of information flow into and out of the device. These paths are known as ''connectors''. Connectors have defined connector types, and each connector type has an associated connector-type name.

�The connectors. Each connector has three values:

-Numeric type of connector. Connection types are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

-InstallName of the driver to which it connects. If left blank, a default connector is used.

-Sequential number of the connector to which it connects. The sample CARDINFO.RC file uses:

&quot;3&quot;,&quot;IBMAMPMIXPAS16&quot;,&quot;1&quot;

where:

3 Indicates the wave stream connector.

&quot;IBMAMPMIXPAS16&quot; Indicates the amplifier-mixer device.

1 Indicates the first connector of the amplifier-mixer device.

�The number of file-name extensions associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file extension. For example, if the .WAV extension is associated with an internal driver name, that driver will be used if a file ending in .WAV is opened.

�The file-name extensions associated with this driver.

�The extended attribute associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file's extended attribute. For example, if the &quot;Digital Audio&quot; extended attribute is associated with an internal driver name, that driver will be used if a file with an extended attribute of &quot;Digital Audio&quot; is opened.

�The AliasName given to the driver. The device ordinal is added to this name if the ordinal is greater than 1. For example, the second Waveform Audio driver would be given an AliasName of Digital Audio 2.

�Any device specific parameters. For the Waveform Audio driver, the following parameters set up the initial state of the adapter, and should be listed:

FORMAT= RIFF Datatype The RIFF Datatype is a format tab defined in \MMOS2\ MMTOOLKT\H\OS2MEDEF.H.

SAMPRATE= Indicates the sample rate.

BPS= Indicates the bits per second.

CHANNEL= Indicates mono (1) or stereo (2).

DIRECTION= Indicates PLAY or RECORD.

For the Audio AmpMixer driver, the following parameters set up the initial state of the adapter, and should be listed.

TREBLE= Indicates the treble setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

BASS= Indicates the bass setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

PITCH= Indicates the pitch setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

GAIN= Indicates the increase in level of output over the level of input setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

BALANCE= Indicates the BALANCE setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

VOL= Indicates the volume setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

INPUT= Specifies LINE or MIC.

OUTPUT= Specifies SPEAKERS or HEADPHONES.

RESOURCEDLL= Specifies the name of the vendor-specific driver resource DLL that you create. For more information, see [[00010.htm|Step 2. Writing a Vendor- Specific Driver]].

RCID Specifies the resource ID in the vendor-specific driver resource DLL that you create. For more information, see [[00010.htm|Step 2. Writing a Vendor- Specific Driver]]. For the Sequencer driver, the following parameters are listed:

CHANNELS= This parameter is followed by 16 1s or 0s to represent whether the sequencer's channels default to on (1) or off (0).

MIDITYPE= This parameter is followed by &quot;General MIDI&quot; if your adapter uses the General MIDI specification. If your adapter does not use General MIDI, you create a MIDI Map Table as specified in [[00019.htm|Step 9. Creating a MIDI Map]]. In this case, the parameter is followed by the adapter name. This name must be the same name used for &quot;keyname&quot; in the MIDIMAP.SCR file in [[00019.htm|Step 9. Creating a MIDI Map]].

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

<pre class="western">RCDATA 12
BEGIN 
    / * * * *   WAVEAUDIO   Driver   * * * * / 
    &quot; IBMWAVEPAS16 &quot;                 / *   Installname   ( 17   chars )                         * / 
    &quot; 7 &quot; ,                            / *   Device   type   ( 3   chars )                          * / 
    &quot; 1 &quot; ,                            / *   Device   flag   ( 3   chars )                          * / 
    &quot; AUDIOMCD &quot; ,                    / *   MCD   driver   name   ( 19   chars )                    * / 
    &quot; AUDIOIF &quot; ,                     / *   VSD   driver   name   ( 19   chars )                    * / 
    &quot; 3 &quot; ,                            / *   Share   Type   ( 3   chars )                           * / 
    &quot; ProAudioSpecW &quot; ,               / *   Resource   name   ( 17   chars )                      * / 
    &quot; 1 &quot; ,                            / *   #   of   Resource   units   ( 2   chars )                 * / 
    &quot; 1 &quot; ,                            / *   #   of   Resource   classes   ( 2   chars )               * / 
    &quot; 1 &quot; ,                            / *   Resource   classes   ( 2   char   each )                * / 
    &quot; 0 &quot; ,                            / *   #   Valid   resource   class   combos   ( 2   chars )      * / 
                                   / *   Valid   resource   class   combos   ( 2   chars   each )   * / 
    &quot; 1 &quot; ,                            / *   #   of   connectors   ( 2   chars )                     * / 
    &quot; 3 &quot; , &quot; IBMAMPMIXPAS16 &quot; , &quot; 1 &quot; ,     / *   Connectors   ( 2   chars ) ,   ( 17   chars ) ,   ( 2   chars ) * / 
    &quot; 1 &quot; ,                            / *   #   of   extensions   ( 2   chars )                     * / 
    &quot; WAV &quot; ,                          / *   Extension   names   ( 3   chars   each )                * / 
    &quot; Digital   Audio &quot; ,               / *   Extended   attribute   ( 255   chars )                * / 
    &quot; Digital   Audio &quot; ,               / *   Alias   Name   ( 17   chars )                          * / 
    &quot; FORMAT = 1 , SAMPRATE = 22050 , BPS = 16 , CHANNELS = 1 , DIRECTION = PLAY &quot; 
                                   / *   Device   Specific   Parameters   ( 255   chars )       * / 
END </pre>
RCDATA 19 This group of parameters indicates:

�The number of prompts that should be presented to the user. This number is used to gather configuration-specific information about the adapter. The maximum is 10 prompts.

�The title of the prompt text as it is displayed to the user.

�The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field.

�The valid answers to your prompt. These answers are displayed to the user . The user can select one.

�The values that are put in your CONFIG.SYS line. These values replace the *VAL* tokens that you placed in your CONFIG.SYS line format previously in this CARDINFO.RC file. These values correspond to the valid answers in the previous field. For example, if the user selects answer number three from the list of valid answers, then value number three is placed into your CONFIG.SYS line. This allows you to ask the user questions in a user- friendly fashion and then place a more cryptic value in the CONFIG.SYS line .

For example, if you want to ask the user which song to play, you can use the following prompt:

<pre class="western">Song to play on startup?</pre>
You can present the following choices to the user:

<pre class="western">Happy Birthday
Beethoven's Fifth
Joy to the World</pre>
The values put into the CONFIG.SYS line could be &quot;birthday.wav&quot;, &quot;beet_5. wav&quot;, or &quot;joyworld.wav&quot;.

�The default answer to the prompt. This is an index into the list of valid answers. For example, if the second answer is the default, specify &quot;2&quot;. For an example of how to specify the RCDATA 19 parameters for this example, see [[00013.htm|Songs Example]].

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

<pre class="western">RCDATA 19
BEGIN
   // Prompts for the User
   &quot;2&quot;,                        /* Number of prompts to ask user (2 chars)    */
                               /* (max 10 prompts)                           */
   // Prompt 1
   &quot;DMA Channel&quot;,              /* Title of Prompt (max 50 chars)             */
   &quot;7&quot;,                        /* # of valid values (2 chars)                */
   &quot;0&quot;,&quot;1&quot;,&quot;2&quot;,&quot;3&quot;,            /* Valid values  (20 chars each)              */
   &quot;5&quot;,&quot;6&quot;,&quot;7&quot;,
   &quot;0&quot;,&quot;1&quot;,&quot;2&quot;,&quot;3&quot;,            /* Corresponding config.sys values            */
   &quot;5&quot;,&quot;6&quot;,&quot;7&quot;,                /* (20 chars each)                            */

   &quot;4&quot;,                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

   // Prompt 2
   &quot;Interrupt Level&quot;,          /* Title of Prompt (max 50 chars)             */
   &quot;8&quot;,                        /* # of valid values (2 chars)                */
   &quot;Interrupt 2&quot;,              /* Valid values (20 chars each)               */
   &quot;Interrupt 3&quot;,
   &quot;Interrupt 5&quot;,
   &quot;Interrupt 7&quot;,
   &quot;Interrupt 10&quot;,
   &quot;Interrupt 11&quot;,
   &quot;Interrupt 12&quot;,
   &quot;Interrupt 15&quot;,

   &quot;2&quot;,                        /* Corresponding config.sys values            */
   &quot;3&quot;,                        /* (20 chars each)                            */
   &quot;5&quot;,
   &quot;7&quot;,
   &quot;10&quot;,
   &quot;11&quot;,
   &quot;12&quot;,
   &quot;15&quot;,

   &quot;6&quot;                         /* Default value - Index into valid values    */
                               /* (2 chars)                                  */
END</pre>






=== Songs Example ===

The following is an example of how to specify RCDATA 19 parameters to ask a user what song to play:

<pre class="western">RCDATA 19
BEGIN
   // Prompts for the User
   &quot;1&quot;,                        /* Number of prompts to ask user (2 chars)    */
                               /* (max 10 prompts).                          */
   // Prompt 1
   &quot;Song to play on startup?&quot;, /* Title of prompt (max 50 chars).            */
   &quot;3&quot;,                        /* Number of valid values (2 chars).          */
   &quot;Happy Birthday&quot;            /* Valid values  (20 chars each).             */
   &quot;Beethoven's Fifth&quot;
   &quot;Joy to the World&quot;

   &quot;birthday.wav&quot;              /* Corresponding CONFIG.SYS values            */
   &quot;beet_5.wav&quot;                /* (20 chars each)                            */
   &quot;joyworld.wav&quot;

   &quot;2&quot;,                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

END</pre>




=== Step 4. Creating an Audio Installation DLL ===

In some cases, you might want to perform some action that is specific to your adapter, and thus not provided by this generic audio installation program. For example, you might want to query the user's hardware setup to determine values, such as interrupt level, rather than prompting the user for those values. In this case, you can create your own DLL to perform these functions.

The audio installation program calls your DLL and allows it to return values that can be added to your lines in the CONFIG.SYS file. The following steps describe how to use your DLL:

1.Write and compile the DLL.

The entry point to your DLL must accept the following parameters:

<pre class="western">CardSpecDLLEntry (USHORT usCardNum,
                  CHAR   achSpec[259])</pre>
where:

usCardNum Is the sequential number of this adapter.

For example, if the user chooses to install two of these adapters, the DLL is called twice. The first time the DLL is called, usCardNum is 1, and the second time the DLL is called, usCardNum is 2.

achSpec[5][259] Is a two dimensional array that can hold up to five strings of 259 characters each. Your DLL can put values into these five strings. The audio installation program then puts these strings into lines in the CONFIG.SYS file as specified in CARDINFO.RC. If there is more than one of these values, they are put into the CONFIG.SYS in sequential order. For example, your DLL fills in the following values:

<pre class="western">achSpec[0]=&quot;rec&quot;
achSpec[1]=&quot;3&quot;
achSpec[2]=&quot;11&quot;
achSpec[3]=&quot;&quot;
achSpec[4]=&quot;&quot;</pre>
The format of your CONFIG.SYS line in CARDINFO.RC is:



<pre class="western">&quot;DEVICE=*PATH*\\MVPRODD.SYS *SPEC* *SPEC* *SPEC*&quot;</pre>
The line that is put into CONFIG.SYS is:



<pre class="western">DEVICE=D:\MMOS2\MVPRODD.SYS rec 3 11</pre>
2.Put the name of the DLL and the name of the DLL's entry point into CARDINFO.RC.





=== Step 5. Modifying the AUDHELP.ITL File ===

AUDHELP.ITL is a help file that gives information to the user when the user installs the audio adapter. Use this file to describe any prompts that ask the user for information. Be careful when modifying this file because the basic format of the file must remain the same for the help to work correctly. If you do not prompt the user for any information, then modify only the first section of the file that explains to the user how many adapters can be installed.





=== Step 6. Running the MAKEFILE ===

The MAKEFILE compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles AUDHELP.ITL into a help file called AUDHELP.HLP.





=== Step 7. Modifying the CONTROL.SCR File ===

You must modify the CONTROL.SCR file so that it contains information relevant to your adapter. This file is the main control file used by MINSTALL, MMPM/2's installation program. CONTROL.SCR tells MINSTALL what subsystems and devices that the user can install.

Modify the following fields in the Audio Adapter Group:

'''Note:'''Do not change the fields ''not''listed here.

ssgroup Specifies the audio adapter group number. The only reason you might need to change this number is if you are installing more than one type of adapter. If you install more than one type of adapter, you must duplicate the entire audio adapter group and change the group number on the second group. If you add one or more groups, you must increment the group count at the top of this file.

ssname Specifies the audio adapter's name.

ssversion Specifies the version number of the device driver.

sssize Specifies the total size (in KB) of the device drivers, the AUDHELP. HLP help file, GENIN.DLL, GENINMRI.DLL, and any other files you install.

ssdllinputparms Matches the ID number used in CARDINFO.RC.

Specifies the MIDI map table. Uncomment this line if you create a MIDI map in Step 9.





=== Step 8. Modifying the AUDFILES.SCR File ===

Modify the AUDFILES.SCR file so that it lists all the files your adapter uses. AUDFILES.SCR tells MINSTALL which files need to be copied, and into which subdirectories those files should be copied.

After changing the list of files in AUDFILES.SCR, change the &quot;Total Number of Files to Copy&quot; in AUDFILES.SCR to match the number of files you have listed.





=== Step 9. Creating a MIDI Map ===

If the audio adapter uses the General MIDI specification, this step is not necessary. When MMPM/2 plays a MIDI file, it maps the patch assignments according to the General MIDI specification. If the audio adapter uses a patch assignment other than General MIDI, you must create a MIDI map table to tell MMPM/2 how to map the patches.

The following steps describe how to create a MIDI map:

1.Modify the MIDIMAP.RC file to hold the MIDI map table.

The MIDIMAP.RC file holds a sample MIDI map table. Modify this table to describe the adapter. The data in MIDIMAP.RC is defined by the MIDITYPE structure. This structure is defined in the MIDITYPE.H file.

<pre class="western">typedef struct {
  USHORT uGenMidiPatchNumber; /* Device To General MIDI Conversion */
  USHORT uDevMidiPatchNumber; /* General MIDI to Device Conversion */
  USHORT uVolumePercent;      /* Channel Patch Volume Scaler */
  USHORT uGenMidiKeyNumber;   /* Device To General MIDI Key Conversion */
  USHORT uDevMidiKeyNumber;   /* General MIDI to Device Key Conversion */
} MIDITYPEENTRY;
typedef MIDITYPEENTRY FAR * PMIDITYPEENTRY;

typedef struct {
   USHORT     uStyle;           /* MIDI Mapping Style */
   USHORT     uDrums10;         /* Patch for Percussion Channel 10 */
   USHORT     uDrums16;         /* Patch for Percussion Channel 16 */
   ULONG      ulReserved;       /* Reserved */
   MIDITYPEENTRY MidiTypeEntry[128];   /* Array of MIDITYPEENTRYs  */
   CHAR       szPatchAndPercKeyName[2*128*40];
                                /* List of 128 Patch Names */
                                /* that are null terminated, then a */
                                /* list of 128 Percussion key names */
                                /* that are double null terminated  */
                                /* Each item is null terminated     */
} MIDITYPE;
typedef MIDITYPE FAR * PMIDITYPE;</pre>
The ''uStyle''field specifies flags that indicate the type of mapping that is required in order to translate from general MIDI to a specific device.

The MT_PERCUSSIONKEYS flag indicates that the device supports percussion keys and that the percussion keys will be translated according to the key conversion tables. If percussion keys are not supported by the MIDI device and MT_MAPPERCKEYPATCHES is specified, then patches on percussion channels will be mapped to the patch indicated in ''uDrums10''or ''uDrums16''. This will enable the mapper to map patch changes on a percussion channel to a drum patch. Individual percussion sounds cannot be mapped but a percussive sound will be heard.

Included in the MIDITYPE data structure is an array of MIDITYPEENTRY structures. This structure includes information for mapping patches and percussion keys between general MIDI and the particular MIDI device.

uGenMidiPatchNumber Describes the mapping of the nth Patch number from the devices patch assignments to general MIDI patch assignments.

uDevMidiPatchNumber Describes the mapping of the nth patch number from the general MIDI patch assignments of the device.

uRelativeVolume Describes the relative volume of the nth patch when mapping from general MIDI to the specified MIDI device.

uGenMidiKeyNumber Describes the mapping of the nth percussion key number from the devices percussion key assignments to general MIDI percussion key assignments.

uDevMidiKeyNumber Describes the mapping of the nth percussion key number from general MIDI percussion key assignments to the devices percussion key assignments.

szPatchAndPercKeyName Lists patch names for each of 128 patches for this MIDI device. Each name is null terminated and the list is double-null terminated. Following the list of patch names is the list of percussion key names for each of 128 keys. These names can eventually be used in a user interface.

2.Modify the MAKEFILE to build the MIDIMAP.RC file into a resource file.

At the end of the MAKEFILE, there is a group of commands that are commented out. These are the commands that build MIDIMAP.RC into MIDIMAP.DLL. Take the comment character (#) off the beginning of each of these lines.

Also in the MAKEFILE are two lines that begin with the word &quot;all.&quot; These should be near the 83rd line. Take the comment character (#) off the beginning of the second line and add a comment character (#) to the beginning of the first line. These lines tell the MAKEFILE which targets to build.

3.Run the MAKEFILE to create the MIDIMAP.DLL resource file.

4.Modify the .INI change file called MIDIMAP.SCR.

In MIDIMAP.SCR, change the keyname from &quot;Your Adapter&quot; to the name of the adapter. This file tells the installation program to install the MIDI map table contained in MIDIMAP.DLL into MMPM/2's MIDITYPE.INI file.

5.Modify the CARDINFO.RC file to name your MIDI map.

In the device-specific parameters field for the Sequencer driver, there is a parameter called MIDITYPE. Set this parameter to the same name used in the MIDIMAP.SCR file in Step 5. For example, you could use MIDITYPE=Your Adapter.

'''Note:'''Make sure that you use the exact spelling (including capitalization) as in MIDIMAP.SCR.

6.Modify CONTROL.SCR so that it calls MIDIMAP.SCR.

The last line of the CONTROL.SCR file contains a line that is commented out . Take the comment characters (/* */) off of this line. This removal causes the installation program to run MIDIMAP.SCR during installation.

7.Modify AUDFILES.SCR to add the MIDIMAP.DLL file.

In the AUDFILES.SCR file, the last file listed is MIDIMAP.DLL. This file is commented out. Remove the comment characters (/*) at the beginning of the line so that your MIDI map file is copied. Increment the number of files at the top of AUDFILES.SCR.





=== Step 10. Creating the Installation Diskette ===

Create a diskette that contains the following files:

�CONTROL.SCR <br />�AUDFILES.SCR <br />�MIDIMAP.SCR (if you created one) <br />�MIDIMAP.DLL (if you created one) <br />�CARDINFO.DLL <br />�AUDHELP.HLP <br />�GENIN.DLL <br />�GENINMRI.DLL <br />�Your device drivers





=== Step 11. Using MINSTALL to Install Your Adapter ===

You can test your installation diskette before sending it to your customers by running MINSTALL.

Before installing the audio adapter, the base MMPM/2 that comes with OS/2 2 .1 (or later) must be installed.

After installing the base MMPM/2, you can install your adapter. The following steps describe how to use MINSTALL:

1.Place the installation diskette in drive A. <br />2.Type '''MINSTALL'''on the OS/2 command line. <br />3.Change the source drive to A. <br />4.Select the adapter. <br />5.If errors occur, check the MINSTALL.LOG file in the \MMOS2\INSTALL subdirectory for error messages.





=== Video Adapter Installation ===

MMPM/2 allows installation of device drivers developed for video adapters into the MMPM/2 video subsystem using a generic video installation program.

This DDK provides a generic video installation program that performs the following functions:

�Asks the user for any information needed to install your adapter, such as the interrupt level.

�Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements.

�Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver.

�Copies the files needed by your adapter, such as device drivers.

The following steps provide an overview of how to install a device driver into the MMPM/2 video subsystem so that it can be used by the Digital Video Recorder to record software motion video. The \MMOS2\MMTOOLKT\SAMPLES\ VIDINST subdirectory provides the generic video installation sample files. For more information about the VIDINST files, see [[00023.htm|Source Code]].





=== Source Code ===

The \MMOS2\MMTOOLKT\SAMPLES\VIDINST subdirectory provides the installation sample files for a video device driver. These sample files illustrate how to install a video device driver into the MMPM/2 video subsystem. The sample files include:

<pre class="western">/-------------------------------------------------------------\
|Sample File              |Description                        |
|-------------------------+-----------------------------------|
|MAKEFILE                 |Creates the resource DLL containing|
|                         |the video adapter information by   |
|                         |compiling the CARDINFO.RC file into|
|                         |the CARDINFO.DLL file. This file   |
|                         |also compiles the VIDHELP.ITL file |
|                         |into the VIDHELP.HLP help file.    |
|-------------------------+-----------------------------------|
|CARDINFO.RC              |Supplies information about the     |
|                         |video adapter.                     |
|-------------------------+-----------------------------------|
|RCSTUB.C                 |Stub 'C' file for compiling        |
|                         |CARDINFO.RC.                       |
|-------------------------+-----------------------------------|
|VIDHELP.ITL              |Contains the help information.     |
|-------------------------+-----------------------------------|
|CONTROL.SCR              |Contains the control information   |
|                         |used by MINSTALL to install the    |
|                         |video adapter.                     |
|-------------------------+-----------------------------------|
|VIDFILES.SCR             |Lists the files to be copied by    |
|                         |MINSTALL.  MINSTALL also copies    |
|                         |this file.                         |
\-------------------------------------------------------------/</pre>
'''Note:'''Before modifying any of these files, make sure you have a backup copy.

More detailed information about each step is provided in the following sections. The steps must be performed in the order listed.

To add a video capture adapter to the MMPM/2 video subsystem, follow these steps:

1.Create an OS/2 device driver for the video capture adapter.

For information on creating an OS/2 device driver, refer to the ''OS/2 Physical Device Driver Reference''.

2.Modify the CARDINFO.RC file.

This file contains specific information about the adapter. MMPM/2 uses this information to interface with the adapter.

For more information, see [[00025.htm|Step 2. Modifying the CARDINFO.RC File]].

3.If necessary, create a DLL to perform actions not provided by this generic video installation program.

This step is not necessary, unless you want to perform some action that is not supported by the generic video installation program. For more information, see [[00027.htm|Step 3. Creating a Video Installation DLL]].

4.Modify the VIDHELP.ITL file.

This file contains information that is presented to the user when installing your adapter.

For more information, see [[00028.htm|Step 4. Modifying the VIDHELP.ITL File]].

5.Run the MAKEFILE.

This file compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles VIDHELP.ITL into a help file called VIDHELP.HLP.

For more information, see [[00029.htm|Step 5. Running the MAKEFILE]].

6.Modify the CONTROL.SCR file.

This file is the control file used by MINSTALL to determine what subsystems and devices a user can install.

For more information, see [[00030.htm|Step 6. Modifying the CONTROL.SCR File]].

7.Modify the VIDFILES.SCR file.

This file lists the files the adapter uses. It tells MINSTALL which files need to be copied, and into which subdirectories to place them.

For more information, see [[00031.htm|Step 7. Modifying the VIDFILES.SCR File]].

8.Create an installation diskette.

This diskette must contain all the files necessary to install the adapter into the MMPM/2 video subsystem using MINSTALL.

For more information, see [[00032.htm|Step 8. Creating the Installation Diskette]].

9.Install your adapter using MINSTALL.

For more information, see [[00033.htm|Step 9. Using MINSTALL to Install Your Adapter]].





=== Step 1. Creating an OS/2 Device Driver ===

For information on creating an OS/2 device driver, refer to the ''OS/2 Physical Device Driver Reference''.





=== Step 2. Modifying the CARDINFO.RC File ===

The CARDINFO.RC file is located in the \MMOS2\MMTOOLKT\SAMPLES\VIDINST subdirectory. Modify this file so that it contains information relevant to your video adapter. MMPM/2 uses this information to interface with the adapter.

'''Notes:'''

1.The lines in this file that contain RCDATA, BEGIN, and END identify the beginning and ending of specific pieces of data. Do not change these lines.

2.If more than one adapter is added, increment each RCDATA number by 10 for each additional adapter. For example, the first adapter uses RCDATA 10 through RCDATA 19, the second adapter uses RCDATA 20 through RCDATA 29, and so forth.

3.If the video adapter does not have a value corresponding to one of the CARDINFO.RC file parameters, use a null string &quot;/0&quot; in the parameter.

The CARDINFO.RC parameters are:

RCDATA 1 Indicates the number of adapters described in this CARDINFO.RC file. In most cases, this is 1. To install more than one type of video adapter, place that number in this parameter.

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

<pre class="western">RCDATA 1
BEGIN
   &quot;1&quot;           /* Number of adapters in this rc file   */
END</pre>
RCDATA 10 Contains two parameters, the ID number and type of adapter used in the CONTROL.SCR file. The ID number can be any number. However, it must match the ''ssdllinputparms''keyword in the CONTROL.SCR file that is modified in [[00030.htm|Step 6. Modifying the CONTROL.SCR File]]. For the type of adapter, the only valid value is &quot;vca.&quot;

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

<pre class="western">RCDATA 10
BEGIN
   &quot;33&quot;,            /* ID number of this adapter */
   &quot;vca&quot;            /* Type of adapter           */
END</pre>
RCDATA 11 Contains parameters that indicate:

�The maximum number of this type of video adapter that can be installed at one time. The maximum is six adapters.

�The name of the help file that describes the video adapter. This name defaults to VIDHELP.HLP if the MAKEFILE provided to create the help file is used.

�The name of the video-adapter-specific DLL you wrote to perform functions not provided by this generic video installation program. This DLL is described in [[00027.htm|Step 3. Creating a Video Installation DLL]]. If you did not write a DLL, specify &quot;\0.&quot;

�The name of the video-adapter-specific DLL entry point into the DLL in the previous field. If you did not write a DLL, specify &quot;\0.&quot;

�The number of CONFIG.SYS lines to add to the user's CONFIG.SYS file to support the video adapter. The maximum is six lines.

�The CONFIG.SYS line format of the lines added to the user's CONFIG.SYS file. Tokens in this line are replaced with the appropriate values at runtime. The following list describes the tokens and their data substitutions:

*PATH* Indicates the path where MMPM/2 was installed (for example, c:\MMOS2 ).

*ORD* Indicates the device ordinal of this adapter.

*SEQ* Indicates the sequential number of this adapter. For example, if the user installs two IBM video capture adapters, the first will have a number of 1 and the second a number of 2.

*PDD* Indicates the PDDName of this adapter.

*VAL* Indicates the values that the user gives when prompted by the installation program. You can have more than one of these tokens if the user is asked for more than one item.

'''Note:'''Later in the CARDINFO.RC file, you specify which questions the install program should ask.

*SPEC* Indicates special values passed from your adapter-specific DLL.

For example, the line in the sample CARDINFO.RC file is:

&quot;DEVICE=*PATH*\\VIDVBC.SYS /*VAL* /*VAL* /*VAL* /*SEQ*&quot;

After the real values are substituted, the CONFIG.SYS line is similar to:

DEVICE=C:\MMOS2\VIDVBC.SYS /0F00000 /2AD6 /I5 /1

�The number of drivers to install into the MMPM/2 system. For a video capture adapter, this would normally be 1 because a Digital Video driver is the only driver installed. The maximum is six drivers.

�The name of the adapter as it is displayed to the user.

�The version number of the device driver.

�The physical device driver name (PDDName) used to identify the device driver. The sequential number of the adapter and a &quot;$&quot; is added to this name to form the final PDDName. For example, if the user installs two Video Blaster** Adapters, the PDDNames are VIDVBC1$ and VIDVBC2$.

�The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'.

�The name of the VSD command table used by the drivers. In most cases, this is blank.

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

<pre class="western">RCDATA 11
BEGIN
   &quot;1&quot;,                        /* Max number of adapters (2 chars)  (6 max)  */
   &quot;vidhelp.hlp&quot;,              /* Helpfile name (19 chars)                   */
   &quot;\0&quot;,                       /* Adapter specific dll name (19 chars)       */
   &quot;\0&quot;,                       /* Adapter specific dll entry point (39 chars)*/

   /**** Data for CONFIG.SYS **/
   &quot;1&quot;,                        /* Number of CONFIG.SYS lines (1 char)        */
   &quot;DEVICE=*PATH*\\VIDVBC.SYS /*VAL* /*VAL* /*VAL* /*SEQ*&quot;,
                               /* CONFIG.SYS Line 1                          */
                               /* (255 chars after token substitution)       */

   /**** Data for INI File ****/
   &quot;1&quot;,                        /* Number of Drivers to Install (1 char)      */
   &quot;Video Blaster&quot;,            /* Product name (39 chars)                    */
   &quot;1.0.0&quot;,                    /* Version of the adapter's software (6 chars)*/
   &quot;VIDVBC&quot;,                   /* PDD Name  (5 chars)                        */
   &quot;MDM&quot;,                      /* MCD table name (19 chars)                  */
   &quot;\0&quot;                        /* VSD table name (19 chars)                  */
END</pre>
RCDATA 12 This group of parameters is repeated for each driver you want to install. The repeated groups should start with RCDATA 13, RCDATA 14, and so forth. These parameters indicate:

�The InstallName of this driver. This must be a unique name. Consider using a name that is a combination of a company name, device type, and device model. The sequential number of this adapter is added to the name (for example, IBMDIGVIDCVB01).

�The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

�The numeric device flag of this driver. Specifies the LONG INT with the flags set. This determines whether or not the device is controllable. The device flags are defined in the MCIOS2.H file located in the \MMOS2\ MMTOOLKT\H subdirectory.

�The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD 'SVMC'.

�The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD 'VIDVCI'.

�The numeric share type. Specifies an encoding of the valid types of sharing supported. These codes are defined in the MMDRVOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

�The name to be given to this driver's resources. Specifies a unique name for the management for the driver resources. The sequential number of the adapter is added to this name so that resources of different drivers are not mixed. If you have more than one driver, be sure to use a different name for each driver. For more information, see [[00034.htm|Resource Units and Classes]].

�The number of resource units supported by this driver. For more information, see [[00034.htm|Resource Units and Classes]].

�The number of resource classes supported by this driver. The maximum is nine resource classes. These classes are listed in the next field. For more information, see [[00034.htm|Resource Units and Classes]].

�The resource classes. For more information, see [[00034.htm|Resource Units and Classes]] .

�The number of valid combinations of resource classes. For more information , see [[00034.htm|Resource Units and Classes]].

�The valid resource class combinations. Resource class combinations are always listed in pairs.

'''Note:'''This field is not in the sample because Video Blaster does not have any valid resource class combinations. If it did, the combination would be listed similar to this:



<pre class="western">&quot;1&quot;,&quot;2&quot;,    (One combines with two)
&quot;2&quot;,&quot;1&quot;,    (Two combines with one)</pre>
For more information, see [[00034.htm|Resource Units and Classes]].

�The number of connectors. These are listed in the next field. The maximum is 10 connectors. Each implementation of a media driver defines the paths of information flow into and out of the device. These paths are known as ''connectors''. Connectors have defined connector types, and each connector type has an associated connector-type name.

�The connectors. Each connector has three values:

-Numeric type of connector. Connection types are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

-InstallName of the driver to which it connects. If left blank, a default connector is used.

-Sequential number of the connector to which it connects.

The sample CARDINFO.RC file uses:

&quot;3&quot;,&quot;&quot;,&quot;1&quot;

where:

3 Indicates the wave stream connector.

&quot;&quot; Indicates the default WaveAudio device.

1 Indicates the first connector of the WaveAudio device.

�The number of file-name extensions associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file extension. For example, if the .AVI extension is associated with an internal driver name, that driver will be used if a file ending in .AVI is opened.

�The file-name extensions associated with this driver.

'''Note:'''This field is not used in the sample because no extensions are associated with the driver for Video Blaster. If there were extensions, they would be listed like the following:

&quot;AVI&quot;, &quot;AVS&quot;

�The extended attribute associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the files extended attribute . For example, if the &quot;Digital Video&quot; extended attribute is associated with an internal driver name, that driver will be used if a file with an extended attribute of &quot;Digital Video&quot; is opened.

�The AliasName given to the driver. This is an alternate name given to the driver. The device ordinal is added to this name if the ordinal is greater than 1. For example, the second DigitalVideo device would be given an AliasName of Digital Video 2.

�Any device specific parameters. These parameters allow you to provide additional information about the driver to the MCD. In most cases, this is blank.

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

<pre class="western">RCDATA 12
BEGIN
   /**** DIGITAL VIDEO Driver ****/
   &quot;IBMDIGVIDCVB&quot;,             /* Installname (17 chars)                     */
   &quot;12&quot;,                       /* Device type (3 chars)                      */
   &quot;1&quot;,                        /* Device flag (3 chars)                      */
   &quot;SVMC&quot;,                     /* MCD driver name (19 chars)                 */
   &quot;VIDVCI&quot;,                   /* VSD driver name (19 chars)                 */
   &quot;3&quot;,                        /* Share Type (3 chars)                       */
   &quot;Video Blaster&quot;,            /* Resource name (17 chars)                   */
   &quot;10&quot;,                       /* # of Resource units (2 chars)              */
   &quot;2&quot;,                        /* # of Resource classes (2 chars)            */
   &quot;10&quot;,&quot;1&quot;,                   /* Resource classes (2 char each)             */
   &quot;0&quot;,                        /* # Valid resource class combos (2 chars)    */
   /* No combos */             /* Valid resource class combos (2 chars each) */
   &quot;1&quot;,                        /* # of connectors  (2 chars)                 */
   &quot;3&quot;,&quot;&quot;,&quot;1&quot;,                 /* Connectors (2 chars), (17 chars), (2 chars)*/
   &quot;0&quot;,                        /* # of extensions (2 chars)                  */
   /* no extension names */    /* Extension names  (3 chars each)            */
   &quot;\0&quot;,                       /* Extended attribute (255 chars)             */
   &quot;Digital Video&quot;,            /* Alias Name (17 chars)                      */
   &quot;\0&quot;                        /* Device Specific Parameters (255 chars)     */
END</pre>
RCDATA 19 This group of parameters indicate:

�The number of prompts that should be presented to the user. This number is used to gather configuration-specific information about the user's adapter. The maximum is 10 prompts.

�The title of the prompt text as it is displayed to the user.

�The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field.

�The valid answers to your prompt. These answers are displayed to the user . The user can select one.

�The values that are put in your CONFIG.SYS line. These values replace the *VAL* tokens that you placed in your CONFIG.SYS line format previously in this CARDINFO.RC file. These values correspond to the valid answers in the previous field. For example, if the user selects answer number three from the list of valid answers, then value number three is placed into your CONFIG.SYS line. This allows you to ask the user questions in a user- friendly fashion and then place a more cryptic value in the CONFIG.SYS line .

For example, you can ask the user if they want to run a hardware test on startup with the following prompt:

<pre class="western">Run hardware test on startup?</pre>
The valid answers that you present to the user could be:

<pre class="western">Yes
No</pre>
The valid values that could be put into the CONFIG.SYS line could be &quot;test&quot; or &quot;notest.&quot;

�The default answer to the prompt. This is an index into the list of valid answers. For example, if the first answer is the default, specify &quot;1.&quot; For an example of how to specify the RCDATA 19 parameters for this example, see [[00026.htm|Startup Example]].

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

<pre class="western">RCDATA 19
BEGIN
   // Prompts for the User
   &quot;3&quot;,                        /* # Number of prompts to ask user (3 chars)  */
                               /* (max 10 prompts)                           */
   // Prompt 1
   &quot;Frame Buffer Base Address&quot;,/* Title of Prompt (max 50 chars)             */
   &quot;8&quot;,                        /* # of valid values (2 chars)                */
   &quot;0F00000&quot;,                  /* Valid values  (20 chars each)              */
   &quot;0E00000&quot;,
   &quot;0D00000&quot;,
   &quot;0C00000&quot;,
   &quot;0B00000&quot;,
   &quot;0A00000&quot;,
   &quot;0900000&quot;,
   &quot;0800000&quot;,
   &quot;1&quot;,                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

   // Prompt 2
   &quot;Base I/O Address&quot;,         /* Title of Prompt (max 50 chars)             */
   &quot;3&quot;,                        /* # of valid values (2 chars)                */
   &quot;2AD6&quot;,                     /* Valid values (20 chars each)               */
   &quot;2A90&quot;,
   &quot;2AF0&quot;,
   &quot;1&quot;,                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

   // Prompt 3
   &quot;Interrupt&quot;,                /* Title of Prompt (max 50 chars)             */
   &quot;4&quot;,                        /* # of valid values (2 chars)                */
   &quot;I5&quot;,
   &quot;I10&quot;,                      /* Valid values (20 chars each)               */
   &quot;I11&quot;,
   &quot;I12&quot;,
   &quot;2&quot;                         /* Default value - Index into valid values    */
                               /* (2 chars)                                  */
END</pre>






=== Startup Example ===

The following is an example of how to specify RCDATA 19 parameters to ask a user if they want to run a hardware setup test:

<pre class="western">
RCDATA 19
BEGIN
   // Prompts for the User
   &quot;1&quot;,                        /* Number of prompts to ask user (3 chars)    */
                               /* (max 10 prompts).                          */
   // Prompt 1
   &quot;Run hardware test on startup&quot;,/* Title of Prompt (max 50 chars).         */
   &quot;2&quot;,                        /* Number of valid values (2 chars).          */
   &quot;yes&quot;                       /* Valid values  (20 chars each).             */
   &quot;no&quot;

   &quot;test&quot;                      /* Corresponding CONFIG.SYS values            */
   &quot;notest&quot;                    /* (20 chars each).                           */

   &quot;1&quot;,                        /* Default value - Index into valid values    */
                               /* (2 chars).                                 */
END
</pre>

=== Step 3. Creating a Video Installation DLL ===

In some cases, you might want to perform some action that is specific to your adapter, and thus not provided by this generic video installation program. For example, you might want to query the user's hardware setup to determine values, such as interrupt level, rather than prompting the user for those values. In this case, you can create your own DLL to perform these functions.

The video installation program calls your DLL and allows it to return values that can be added to the CONFIG.SYS file. The following steps describe how to use your DLL:

1.Write and compile the DLL.

The entry point to your DLL must accept the following parameters:

<pre class="western">CardSpecDLLEntry (USHORT usCardNum,
                  CHAR   achSpec[5][259])</pre>
where:

usCardNum Is the sequential number of this adapter.

For example, if the user chooses to install two of these adapters, the DLL is called twice. The first time the DLL is called, usCardNum is 1, and the second time the DLL is called, usCardNum is 2.

achSpec[5][259] Is a two dimensional array that can hold up to five strings of 259 characters each. Your DLL can put values into these five strings. The video installation program then puts these strings into lines in the CONFIG.SYS file as specified in CARDINFO.RC. If there is more than one of these values, they are put into the CONFIG.SYS in sequential order. For example, your DLL fills in the following values:

<pre class="western">achSpec[0]=&quot;rec&quot;
achSpec[1]=&quot;3&quot;
achSpec[2]=&quot;11&quot;
achSpec[3]=&quot;&quot;
achSpec[4]=&quot;&quot;</pre>
The format of your CONFIG.SYS line in CARDINFO.RC is:

DEVICE=*PATH*\\VIDVBC.SYS *SPEC* *SPEC* *SPEC*

The line that is put into CONFIG.SYS is:

DEVICE=D:\MMOS2\VIDVBC.SYS rec 3 11

2.Put the name of the DLL and the name of the DLL's entry point into CARDINFO.RC.





=== Step 4. Modifying the VIDHELP.ITL File ===

VIDHELP.ITL is a help file that gives information to the user when the user installs the video adapter. Use this file to describe any prompts that ask the user for information. Be careful when modifying this file, because the basic format of the file must remain the same for the help to work correctly. If you do not prompt the user for any information, then modify only the first section of the file that explains to the user how many adapters can be installed.





=== Step 5. Running the MAKEFILE ===

The MAKEFILE compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles VIDHELP.ITL into a help file called VIDHELP.HLP.





=== Step 6. Modifying the CONTROL.SCR File ===

Modify the CONTROL.SCR file so that it contains information relevant to your adapter. This file is the main control file used by MINSTALL, MMPM/2's installation program. CONTROL.SCR tells MINSTALL which subsystems and devices that the user can install.

Modify the following fields in the Video Adapter Group:

'''Note:'''Do not change the fields not listed here.

ssgroup Specifies the video adapter group number. The only reason to change this number is if you are installing more than one video adapter. If you install more than one type of adapter, you must duplicate the entire video adapter group and change the group number on the second group. If you add one or more groups, you must increment the group count at the top of this file.

ssname Specifies the video adapter's name.

ssversion Specifies the version number of your device driver.

sssize Specifies the total size (in KB) of your device drivers and the VIDHELP.HLP help file.

ssdllinputparms Matches the ID number used in CARDINFO.RC.





=== Step 7. Modifying the VIDFILES.SCR File ===

Modify the VIDFILES.SCR file so that it lists all the files the adapter uses. VIDFILES.SCR tells MINSTALL which files need to be copied, and into which subdirectories those files should be copied.

After changing the list of files in VIDFILES.SCR, change the &quot;Total Number of Files to Copy&quot; in VIDFILES.SCR to match the number of files you have listed.





=== Step 8. Creating the Installation Diskette ===

Create a diskette that contains the following files:

�CONTROL.SCR <br />�VIDFILES.SCR <br />�CARDINFO.DLL <br />�VIDHELP.HLP <br />�Your device drivers





=== Step 9. Using MINSTALL to Install Your Adapter ===

You can test your installation diskette by running MINSTALL. Before installing the video adapter, you must install:

�OS/2 Version 2.1 (or later)

�MMPM/2

�The files that came with this DDK.

After installing the base MMPM/2, you can install your adapter. The following steps describe how to use MINSTALL:

1.Place the installation diskette in drive A. <br />2.Type '''MINSTALL'''. <br />3.Change the source drive to A. <br />4.Select the adapter. <br />5.If errors occur, check the \MMOS2\INSTALL\MINSTALL.LOG file.





=== Resource Units and Classes ===

Device contexts are managed by the Media Device Manager (MDM), using an abstract concept of resource units, resource classes, and valid class combinations.

Resource units provide a measurement for the resource manager to determine how many device contexts can be active at any given time. Each device specifies how many resource units it can process concurrently.

In addition to a total resource number, each resource class has a maximum number of resource units available to it. This allows the MDM to determine how many device contexts from a particular class can be active concurrently . During the installation procedure the maximum numbers are provided.

On the MCI_OPEN of a device context the required resource units and class for the device context is returned in the MMDRV_OPEN_PARMS structure. The required resource units and resource class of a device context can be changed by the MCD by calling the MDM with the MCIDRV_CHANGERESOURCE message. For example, if a waveaudio device allocated one resource unit for a mono wave and two units for a stereo wave, then a load command might change the required units for that device context.

The final piece of resource management is provided during installation. This piece is the valid class combinations. A certain device might have multiple classes but might not allow certain classes to have active device contexts concurrently.

For further information on Resource Units and Classes, refer to the ''OS/2 Multimedia Subsystem Programming Guide''





=== Audio Physical Device Driver Template ===

This DDK provides two working samples for writing your own audio physical device drivers for the MMPM/2 environment:

�For wave audio/midi, the Turtle Beach &quot;Tropez Plus&quot; device driver. See the document &quot;Object-oriented OS/2 Audio Device Driver Sample&quot; which resides on the DDK Web page for details. <br />�For wave audio, the IBM-written AD1848 Business Audio device driver.

These samples include all the code required for communication with MMPM/2- including establishing communication with MMPM/2, controlling specific hardware devices, and establishing inter-device driver (IDC) communications with the MMPM/2 stream handlers and IOCtl-based communications with the MMPM/2 amplifier-mixer (ampmix) and media control drivers (MCDs).

'''Note:'''For further information on when to use a physical device driver (PDD ) and how it operates, see the online ''OS/2 Physical Device Driver Reference''provided in this package. This reference describes the types of physical device drivers, their interfaces, and available system services.





=== PDD Architecture ===

The MMPM/2 audio PDD is a standard OS/2 PDD. Audio PDDs have two entry points for communication with the system. The OS/2 device driver standard strategy entry point is used for open/close and setup operations-received from application-level components. Data movement is done via Ring-0 interdevice driver (IDC) interface. These interfaces provide the foundation for sharing of the audio device by MMPM/2 applications and media drivers.

The audio IOCtls are standard OS/2 IOCtls. Definitions follow in this chapter. Media drivers running at Ring 3 use the IOCtl interface to set up the audio device sample rate, for access, to change volume controls, and so on. The IOCtl interface is not meant to be used to send audio data to the device driver.

The IDC interface is standard 16:16 to 16:16 for procedure calls, initiated by the OS/2 AttachDD DevHlp function. Stream handler device drivers and audio physical device drivers use the IDC interface to communicate with one another to coordinate their efforts to stream data to and from the audio device.

The following graphic shows the audio physical device driver architecture. [Artwork not shown]

The IDC Interface

Two entry points are provided for the two device drivers participating in the IDC interface, [[00155.htm|DDCMDEntryPoint]]and [[00212.htm|SHDEntryPoint]]. [[00155.htm|DDCMDEntryPoint]]allows the stream handler device driver to call to the PDD, and [[00212.htm|SHDEntryPoint]]allows the audio PDD to call to the stream handler.

Note that streaming data buffer pointers are passed by the Sync/Stream Manager to the audio stream handler by means of Sync/Stream Manager Helper (SMH) calls. Then the audio stream handler passes pointers to the PDD using device driver command (DDCMD) messages.

The following graphic shows the audio physical device driver modules. [Artwork not shown]

Communication to the PDD

[[00154.htm|DDCMD Messages]]are defined from the [[00155.htm|DDCMDEntryPoint]]. Each message represents a specific request by the stream handler for the audio PDD to perform an action.

Read and write messages allow the stream handler to get and receive data directly from the PDD without any intervention required by the application. The application neither has to send data through an IOCtl nor allocate and lock memory to perform data transfers.

Communication to the Stream Handler

The [[00212.htm|SHDEntryPoint]]contains the following two messages. These messages are located in the SHDD.H file of the \MMOS2\MMTOOLKT\H subdirectory. SHDD.H contains the data structures, their type definitions, and #define statements for certain values. Note that the messages pass pointers to packets of data, to allow maximum flexibility for the future.

[[00227.htm|SHD_REPORT_INT]]The PDD uses this message when it needs data at interrupt time. For example, it uses this message to tell the stream handler it has used up all the data and needs more.

When the stream handler gets the call, it knows the PDD is passing back a buffer that it might already have consumed. So the stream handler returns on that call, giving the PDD a fresh buffer to consume.

[[00220.htm|SHD_REPORT_EVENT]]The stream handler uses this message to keep in sync with PDD activities. For example, the stream handler can request the PDD to report back every tenth of a second that data is played. The stream handler has all the logic to handle these events. The PDD examines the request, and during its checks when it realizes a tenth of a second has been played in data, the PDD calls SHD_REPORT_EVENT. The stream handler can do what it wants at this point, and the PDD returns.

The PDD keeps track of the processes. In other words, only the PDD knows how much data, to the millisecond, has been played out to the device. The stream handler can approximate the data played, using calculations based on how much data has gone by. But the stream handler cannot calculate the data played to the millisecond, or even to the fraction of a millisecond, the way the PDD can.

Stream Handler Values

There are certain values that the stream handler is expecting. For example , when the stream handler requests a stop or a pause on a [[00162.htm|DDCMD_CONTROL]]message, the pointer that comes back to the stream handler is a pointer to the cumulative time that the PDD has recorded in real time. So whenever the stream handler requests the device to stop, the PDD honors that request and informs the stream handler the real time that the PDD stopped within the stream.

Another value the stream handler looks for is returned on [[00197.htm|DDCMD_STATUS]]. This is also a pointer to the cumulative time from the PDD, with respect to when that stream was first started at the stream handler's request.

PDD Values

The stream handler passes a pointer to the PDD on [[00197.htm|DDCMD_STATUS]]. This points to a value used by the PDD for setting the referenced time of the PDD. It is not always correct for the PDD to start its time at 0 every time the stream handler does a start, because the stream handler might have performed a seek in the stream. The PDD might have played a minute of data and then performed a backwards seek to the 30-second mark in the data. If a start is issued, the PDD should start from the 30-second mark in that stream.

[[00162.htm|DDCMD_CONTROL]]has an important NOTIFY subfunction, which is used for cuepoint or event detection. The stream handler supports events in cuepoints-an application request to be notified when a particular location in the file is reached or a specific time period has elapsed. The stream handler uses two methods for detecting how much time has elapsed:

�Using DDCMD_CONTROL NOTIFY, the stream handler requests to be notified by the PDD at a particular time and passes a pointer to the cue time.

�The stream handler determines the time internally. This method is not as precise as the first method, because only the PDD knows the real time.

For example, suppose the stream handler does a DDCMD_CONTROL NOTIFY at one minute. If the PDD supports precise event detection, it must accept this request and put it into a queue somewhere, preferably a linked list. This linked list will have the time of one minute so that during the streaming process, the PDD occasionally checks to see whether it is at the one minute mark. When this event occurs, the PDD calls back on an [[00220.htm|SHD_REPORT_EVENT]]. Then you can free up the event detection linked list node.

Keep in mind that the PDD should have the capability to queue these requests because there might be additional requests. For example, an application might request to be notified at the one-minute mark, next at a minute and a half, and possibly every five minutes.

If the PDD does not support event detection, then when it gets called on a DDCMD_CONTROL NOTIFY, it responds with an ERROR_INVALID_REQUEST. This response tells the stream handler that it must do the event-detection itself.





=== Source Code for the Object-oriented Audio Device Driver ===

Source code for the object-oriented audio device driver, TROPEZ.SYS, which supports the Turtle Beach &quot;Tropez Plus&quot; audio card is located on the DDK Web page. Documentation describing the driver sample can be viewed with a browser at the following Web page:

<pre class="western">   http://service.boulder.ibm.com/ddk/</pre>
Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.





=== Source Code for AD1848 PDD ===

Source code for the AD1848 device driver is located in the \MMOS2\MMTOOLKT\ SAMPLES\AD1848 subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.

<pre class="western">/-------------------------------------------------------------\
|Source File              |Description                        |
|-------------------------+-----------------------------------|
|AD1848.C                 |This file contains functions that  |
|                         |interface with the Analog Device   |
|                         |stereo codec AD1848.               |
|-------------------------+-----------------------------------|
|AUDCONT.C                |This file contains functions that  |
|                         |support audio control commands from|
|                         |the DosDevIoctl interface to the   |
|                         |device driver.                     |
|-------------------------+-----------------------------------|
|DMA.C                    |This file contains routines that   |
|                         |support DMA services.              |
|-------------------------+-----------------------------------|
|HEADER.C                 |This file contains device driver   |
|                         |header information.                |
|-------------------------+-----------------------------------|
|MEM.C                    |This file contains functions       |
|                         |related to dynamic memory          |
|                         |allocation.                        |
|-------------------------+-----------------------------------|
|PARAM.C                  |This file contains routines that   |
|                         |parse parameters from the device   |
|                         |assignment statement in the        |
|                         |config.sys file.                   |
|-------------------------+-----------------------------------|
|PRINTF.C                 |This file contains routines to     |
|                         |implement C printf functions for   |
|                         |writing messages to console during |
|                         |initialization and to COM: port    |
|                         |during execution for debugging.    |
|                         |COM: support is ifdefed out of     |
|                         |driver for production builds.      |
|-------------------------+-----------------------------------|
|STRATEGY.C               |This file contain the routine that |
|                         |services the device driver strategy|
|                         |entry point and routines that      |
|                         |support the vdd interface.         |
|-------------------------+-----------------------------------|
|STRING.C                 |This file contains miscellaneous   |
|                         |string utility functions.          |
|-------------------------+-----------------------------------|
|STRMCONT.C               |This file contains functions that  |
|                         |service requests from the audio    |
|                         |stream handler and report events to|
|                         |the audio stream handler.          |
|-------------------------+-----------------------------------|
|STRMHELP.C               |This file contains routines that   |
|                         |support stream related services.   |
|-------------------------+-----------------------------------|
|TIMER.C                  |This file contains miscellaneous   |
|                         |time related functions.            |
|-------------------------+-----------------------------------|
|TRACE.C                  |This file contains routines that   |
|                         |support the data logging facility  |
|                         |used for device driver debugging   |
|                         |and performance analysis.          |
|-------------------------+-----------------------------------|
|AUDCONT.H                |This file contains prototypes for  |
|                         |public functions originating in    |
|                         |AUDCONT.C                          |
|-------------------------+-----------------------------------|
|DEVHELP.H                |This file contains prototypes for  |
|                         |public functions in DEVHLP.ASM.    |
|-------------------------+-----------------------------------|
|DEVICE.H                 |This file contains definitions for |
|                         |shared constants and prototypes for|
|                         |public functions that originate in |
|                         |DEVICE.C.                          |
|-------------------------+-----------------------------------|
|DMA.H                    |This file contains prototypes for  |
|                         |public functions and definitions   |
|                         |for shared constants originating in|
|                         |DMA.C.                             |
|-------------------------+-----------------------------------|
|ECHO.H                   |This file contains prototypes for  |
|                         |public functions originating in    |
|                         |ECHO                               |
|-------------------------+-----------------------------------|
|END.H                    |This file contains prototypes for  |
|                         |public functions in END.C.         |
|-------------------------+-----------------------------------|
|DEVHLP.ASM               |This file contains routines that   |
|                         |support device driver helper       |
|                         |services from the operating system.|
|-------------------------+-----------------------------------|
|ENTRY.ASM                |This file contains functions that  |
|                         |support all the entry points into  |
|                         |the driver.                        |
|-------------------------+-----------------------------------|
|UTIL.ASM                 |This file contains miscellaneous   |
|                         |utility functions for io port data |
|                         |transfer, memory data transfer, and|
|                         |address manipulation.              |
\-------------------------------------------------------------/</pre>




=== Data Transfers ===

Following are the two methods of transferring data:

Direct Memory Access (DMA) The most efficient way to transfer data from the host system to the audio adapter's memory is through direct memory access ( DMA). This is a technique for moving data directly between main storage without requiring processing of the data by the CPU. To accomplish this, we create a DMA buffer within the device driver to transfer the data. As the device driver receives the stream buffer data, it copies the stream buffer data into the DMA buffer at interrupt time. When the DMA buffer is full, it can be sent directly to the audio device. A preferable (but unproven) method would be to DMA directly from the stream buffer. Currently, however, a copy operation (which requires time and CPU utilization) is required to get data into the AUDIODD DMA buffer.

To perform direct memory access, you are essentially programming the DMA microcontroller on the system board. For each direct memory access, you can DMA transfer data up to the limit of the DMA channel that the audio adapter is using:

- 64KB for the 8-bit DMA channels 0, 1, and 3

- 128KB for the 16-bit DMA channels 5, 6, and 7

Note that this DMA transfer must always be from the same buffer pointer. Unless you decide to change the buffer pointer, you would have to reprogram the microcontroller from the beginning.

Therefore, if you want to DMA directly from the stream buffer, your device driver would always require a different pointer which means reprogramming the DMA controller at each interrupt. So, each time you get a new buffer from the stream handler, you would have to look at the pointer, reprogram the DMA controller, and then start the DMA transfer. At this stage, most developers state that there is not enough time to reprogram the DMA controller during interrupt time. Therefore, they are creating one DMA buffer when the device driver is initialized at system startup. The developer programs the DMA controller at that point, informs the controller that this is the pointer, and tells it how much data the device driver is going to transfer. The value is set for the lifetime of the driver.

Dual DMA Buffers

MMPM/2's stream handler implementation uses two DMA buffers or ''dual DMA buffers''to ensure a smooth flow of audio data.

In this implementation, the amplifier-mixer (ampmix) device issues a request through the OS/2 kernel to the audio PDD for it to prepare to process audio data. The audio PDD informs the stream handler that it needs the audio data, and the stream handler informs the file system PDD to fill two 4KB DMA buffers with the appropriate audio data.

When the audio PDD processes the first 4KB buffer, it issues a hardware interrupt that signals the file system PDD to replace the first 4KB buffer with the next 4KB of audio data. Meanwhile, the audio PDD is processing the second 4KB buffer. When the audio PDD processes the second 4KB buffer, it issues a hardware interrupt again and the process is repeated.

With this process, you only have to track two DMA buffers and the stream handler ensures a smooth flow of audio data to the audio PDD. The following illustration provides an overview of this process.

<pre class="western">                1st 4KB DMA    2nd 4KB DMA
               /---------------------------\
          /---�|             |             |
          |    |             |             |
          |    \---------------------------/
          |                  �             �
/----------------------\     \---------------The audio PDD
|                      |                     issues hardware
| /-----------------\  |                     interrupts when it
| | Stream Handler  |  |                     finishes processing
| \---- - ------- - ---- /    |                         each   4KB   DMA   block . 
|     �    |         |    �      | 
|     |    |         |    |      | 
|     |    �         �    |      |        The   stream   handler   manages 
|   / - - ----- \    / ---- - -- \   |        the   process   of   the   audio 
|   | Audio    |    | File     |   |        PDD   processing   4KB   DMA 
|   | PDD      |    | System   |   |        blocks   and   the   file   system 
|   |         |    | PDD      |   |        PDD   replacing   the   block   as 
|   \ ------- /    \ ------- /   |        it   is   processed . 
\ ---------- ---------- -- / </pre>
Programmed I/O Programmed I/O involves copying the stream buffer's data directly to the adapter's buffer.





=== Stream Descriptions ===

Each physical device driver supports the following:

Multiple Opens A PDD must be able to handle multiple open operations. In other words, the OS/2 operating system should be able to open your device driver as many times as necessary. However, resource should only be allocated at the audio initialization stage (IOCtl stage).

Multiple Streams A PDD must be able to handle multiple streams. For example, there might be ten multimedia programs on the desktop that have the device open. However, only one program can own the device. For that one program, a stream is created and resources are used. However, if that one program gets put to sleep or the audio is paused, a second program can take its place and use that resource. The Media Device Manager will save pointers to the stream instance that is currently paused, point to the next program, and allow the program to use the resource. At this point, there will be two streams created. If the second program gets initialized, and perhaps paused, the third program will be initialized, and so on.

Many streams can be created, however, the program that has focus is the program using the adapter. In addition, a device driver might have ten streams allocated but only one stream will be active at a given time if the hardware supports only one stream. Some hardware can support more than one active stream at a time. For example, the ACPA card can play two mono streams at the same time but only one stereo.

Multiple Streams Implementation A stream table is a collection of streams with each stream having different data-similar to a data instance for DLLs. For example, one stream might be set up for recording using specific data rates and buffer pointers, while another stream might be set up for playback of a different data rate and buffer pointers. The two streams are unaffected by each other. The hardware will react to whichever stream is active.

A stream table contains the key indexes to determine which stream to make active. The key indexes are ''hStream''and ''ulSysFileNum''. The ''hStream''comes from the stream handler during stream registration while the ''ulSysFileNum''comes from both the DDCMD_REGISTER message and the AUDIO_INIT IOCtl. For example, in the following table, stream #1 has a system file number of 6B and stream #2 has a system file number of 7C. When the AUDIO_INIT IOCtl comes in to start the second instance, the IOCtl requests that you start the stream with the matching ''ulSysFileNum''. Next, across the inter-device driver communications interface, the stream handler will tell you to start stream #2. To start stream #2, search the stream table for a match with system file number #7C. If you find a match, make the stream active. If you do not find a match, the operation fails.

<pre class="western">                        IOCtl
                        ulSysFileNum
                           |
                           |
                           �
                hstream  sysfile#  state  data  pData
               /--------------------------------------\
  IDC          |   1    |  6B    |      |     |       |
  hStream      |--------|--------|------|-----|-------|
  ---------�   |   2    |  7C    |      |     |       |
               |--------|--------|------|-----|-------|
               |   3    |  8D    |      |     |       |
               \--------------------------------------/</pre>






=== Roadmaps ===

The following figures illustrate the routines and IOCtls included in the audio physical device driver files.





=== STARTUP.ASM ===



<pre class="western">                           STARTUP.ASM File
                        /---------------------\
OS/2 IOCtls ----------� |   AUDIODD.C         |
                        |                     |
Stream Handler IDC ---� |   MMDDCMDS.C        |
                        |                     |
VDD IDC --------------� |   AUDIOVDM.C        |
                        |                     |
VDD �----------------   |    CallVDD()        |
                        \---------------------/</pre>




=== AUDIODD.C ===



<pre class="western">    AUDIODD.C File
   /------------------------------------------\
   | Strategy.C()                             |
   |  |                                       |
   |  |-� IOCTL_Init()                        |
   |  |-� IOCTL_Invalid()                     |
   |  |-� IOCTL_Read()                        |
   |  |-� IOCTL_NondestructiveRead()          |
   |  |-� IOCTL_ReadStatus()                  |
   |  |-� IOCTL_FlushInput()                  |
   |  |-� IOCTL_Write()                       |
   |  |-� IOCTL_WriteStatus()                 |
   |  |-� IOCTL_FlushOutput()                 |
   |  |-� IOCTL_Input()                       |
   |  |-� IOCTL_Output()                      |
   |  |-� IOCTL_Open()                        |
   |  |-� IOCTL_Close()                       |
   |  \-� IOCTL_GenIOCTL()                    |
   |             |                            |
   |             |-� Audio_IOCTL_Init()       |
   |             |-� Audio_IOCTL_Status()     |
   |             |-� Audio_IOCTL_Control()    |
   |             |-� Audio_IOCTL_Buffer()     |
   |             |-� Audio_IOCTL_Load()       |
   |             |-� Audio_IOCTL_Wait()       |
   |             \-� Audio_IOCTL_Hpi()        |
   |                                          |
   | InitPos()                                |
   | InitStreams()                            |
   | AllocDMABuffer()                         |
   | ParseArgs()                              |
   \------------------------------------------/</pre>




=== MMDDCMDS.C ===



<pre class="western">    MMDDCMDS.C File
   /------------------------------------------\
   | DDCMDInternalEntryPoint()                |
   |  |                                       |
   |  |-� DDCMDSetup()                        |
   |  |-� DDCMDRead()                         |
   |  |-� DDCMDWrite()                        |
   |  |-� DDCMDStatus()                       |
   |  |-� DDCMDControl()                      |
   |  |-� DDCMDRegister()                     |
   |  \-� DDCMDDeRegister()                   |
   |                                          |
   | GetStreamEntry()                         |
   \------------------------------------------/</pre>




=== AUDIOVDM.C ===



<pre class="western">    AUDIOVDM.C File
   /------------------------------------------\
   | PDDInternalEntryPoint()                  |
   |                                          |
   | VDMInterruptTime ()                      |
   |  |                                       |
   |  \-� CallVDD()                           |
   |                                          |
   | VDMClose()                               |
   |  |                                       |
   |  \-� CallVDD()                           |
   \------------------------------------------/</pre>




=== AUDINTR.C ===



<pre class="western">    AUDINTR.C File
   /-------------------------------------------------\
   | InterruptHandler()                              |
   |  |                                              |
   |  |-� VDMInterruptTime()                         |
   |  |-� WriteDatatoCard()                          |
   |  |-� SHDEntryPoint() call back to stream handler|
   |  \-� EOI()                                      |
   \-------------------------------------------------/</pre>




=== CDEVHLP.ASM ===



<pre class="western">    CDEVHLP.ASM File
   /------------------------------\
   | DevHlp_AllocGDTSelector()    |
   | DevHlp_AllocPhys()           |
   | DevHlp_PhysToGDTSelector()   |
   | DevHlp_PhysToVirt()          |
   | DevHlp_VirtToLin()           |
   | DevHlp_ABIOSCall()           |
   | DevHlp_GETLIDEntry()         |
   | DevHlp_FreeLIDEntry()        |
   | DevHlp_RegisterPDD()         |
   | DevHlp_AttachDD()            |
   \------------------------------/</pre>




=== Audio Virtual Device Driver Template ===

The ''IBM Developer Connection Device Driver Kit for OS/2''includes full source for the MMPM/2 provided Virtual Device Driver, VBSAUDIO.SYS. Use VBSAUDIO.SYS to serialize DOS application access to audio hardware in the MMPM/2 environment. This VDD can communicate with multiple audio PDDs through the [[00052.htm|Inter-Device Driver Communication (IDC) Interface]]. However, where the services of VBSAUDIO.SYS are not sufficient, you can modify the audio VDD template to meet your device driver requirements.

You can code your Physical Device Driver to meet the interfaces of VBSAUDIO .SYS as an initial step toward virtualization. You can expand this functionality by copying and changing VBSAUDIO.SYS to take advantage of your hardware and private interfaces which can be established between the VDD and DOS or WIN-OS/2 audio device drivers.

'''Note:'''For further information on when to use a VDD and how it operates, see the online ''OS/2 Virtual Device Driver Reference''provided in this package. This reference describes the types of virtual device drivers, their interfaces, and available kernel services.





=== Source Code ===

The VDD template is written using Watcom C and linked with the 32-bit OS/2 linker. Source code for the audio VDD sample is located in the \DDK\BASE\ SRC\VDEV\MME\VBSAUDIO subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.





=== VDD Architecture ===

The VBSAUDIO.SYS virtual device driver is a Ring 0, 32-bit device driver responsible for controlling multiple virtual DOS sessions. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely.

VDD architecture usually calls for a device driver pair: a PDD and VDD working together to serialize and control a common piece of hardware, called ''shared hardware''. The PDD controls access to the hardware and OS/2 sessions; the VDD controls DOS sessions and communicates with the PDD to serialize access. That is, the PDD and VDD communicate to make sure DOS sessions and OS/2 sessions cannot concurrently access the shared hardware.

Without a VDD, DOS sessions have complete access to system hardware. Most DOS visible hardware resources are controlled by system VDDs, preventing DOS sessions from interfering with each other and protecting OS/2 applications from DOS sessions.

When a PDD exists with no VDD, the hardware device is visible to the OS/2 side (through the PDD) and to all DOS sessions (through the VDM Manager). This presents an opportunity for DOS sessions to take control of a hardware resource owned by an OS/2 PDD. Writing a virtual device driver corrects this situation, resulting in system-wide protected access to the hardware resource.

This PDD-VDD pair usually results in a VDD (like a PDD) being written to the specifications of a specific hardware device. VBSAUDIO.SYS supports multiple adapters by using a protocol for PDD-VDD communication where the PDD defines the characteristics of its device at system startup. [Artwork not shown]

The key to supporting multiple PDDs is communication at system startup to attain a description of the physical characteristics of each adapter. PDDs are loaded and initialized prior to VDDs. When the PDD loads, it registers itself as willing to communicate with VDDs by providing its IDC name and entry point for this communication. When the VDD loads, it calls a Virtual DevHlp service (VDHOpenPDD) to resolve the IDC entry point of the PDD. On this call, the operating system calls the PDD to deliver the VDD IDC entry point. When the PDD and VDD exchange entry points, the drivers are free to communicate through whatever private protocol is chosen including exchanging register-based entry points.

For these calls to function, the VDD must know the name by which the PDD registered. In a non-generic implementation, this is not a problem as the two device drivers can refer to the name from a common include file. This &quot;generic&quot; VDD takes the PDD names as DEVICE=VBSAUDIO.SYS parameters on the CONFIG.SYS statement.

In the case where a single PDD supports multiple devices, the PDD should register its IDC name and entry point (specifying the name on the DEVICE= VBSAUDIO.SYS statement). During initialization, the VDD calls the PDD to establish communication and to query the hardware resources that the PDD controls. The VDD will use this information to trap DOS session attempts to access the adapter. When a DOS session takes control of a PDD-owned resource, the VDD traps the DOS session pending permission to use the hardware. As the PDD controls access, the VDD queries the PDD for permission to use the hardware. If permission is granted, the VDD disables further traps and allows the DOS session to continue uninterrupted. Traps are disabled to give maximum performance. Because the VDD does not keep track of port accesses (and does not know the details of supported adapters ), it is unable to remember the state of the adapter. That is, as soon as a DOS session owns the hardware, ownership cannot be relinquished and restored, because the VDD does not know how to restore the state of the device. The VDD supports serialization (not virtualization).

If access is denied by the PDD, or if another DOS session already owns the hardware, a pop-up message is displayed asking the user for direction. The user can give instruction to terminate the session, suspend the session, or pretend the hardware does not exist. Based on this response, the VDD executes Virtual DevHlp services to perform the necessary actions. Semaphores are used to block DOS session execution when they are suspended awaiting access to hardware. When the last DOS session releases the hardware, the VDD returns hardware ownership to the PDD.

'''Note:'''See [[00051.htm|VDD Operations]]for further information.





=== VDD Operations ===

When writing a PDD to control physical hardware, it is common to write a VDD to provide serialization with DOS sessions. Without a VDD, DOS sessions have complete access to system resources. That is, if an adapter has only a PDD, DOS sessions can directly access the adapter resulting in unpredictable consequences.

When DOS sessions are created, the VDD installs hooks for the indicated port ranges. On first access, the DOS session is said to be &quot;requesting hardware access.&quot; By convention, the PDD controls hardware access. To gain use, the VDD must ask the PDD for permission to use the hardware. When granted, the DOS session traps are removed and the session is allowed to continue executing. At interrupt time, the PDD calls the VDD IDC entry point where the VDD virtualizes the hardware interrupt for the owning session.

Subsequent DOS session access attempts are denied pending hardware availability. A hard error pop-up window is displayed giving the user three options:

�End - Terminate the DOS session <br />�Retry - Block until hardware becomes free <br />�Ignore - Instruct the VDD to ignore the adapter

If retry is chosen, the DOS session is blocked until the hardware becomes available. When the DOS session in use releases the hardware, the next DOS session gains access. This process continues until no more devices are waiting at which point the VDD relinquishes ownership to the PDD.

If ignore is chosen, the DOS session continues execution but with no visibility to the protected adapter. This allows sound-enabled DOS applications to execute under the impression that the system does not have an audio card installed.

For access queues, the PDD uses semaphores and the OS/2 scheduler. The VDD maintains no queues. Instead, 1 mutex and 1 event semaphore are used to control access. Only one DOS session can own the hardware at any one time. When the VDD owns the hardware, the DOS session owning the mutex semaphore is allowed to execute. All others are blocked pending hardware availability. When the owning session releases the hardware (the semaphore ), the OS/2 semaphore routines and scheduler determine which session next gains access.

A DOS session can also be denied access due to OS/2 PDD refusal to relinquish ownership. This would be the case when an OS/2 application is using the services of the PDD before a DOS session attempts access. Here, all pending DOS sessions are queued waiting on an event semaphore. When the OS/2 PDD relinquishes hardware, all blocked sessions are allowed to run by posting the event semaphore. The sessions compete for ownership of the mutex semaphore. One session wins, the others block; serialization is maintained.





=== Inter-Device Driver Communication (IDC) Interface ===

Virtual device drivers (VDDs) communicate with physical device drivers ( PDDs) through the inter-device driver communication (IDC) interface provided with the OS/2 operating system. The drivers exchange the address of an entry point and call each other through the exchanged addresses. A VDD communicates with a PDD directly through a callable 16:32 interface or by using the Virtual DevHlp services that map to File System APIs.

Physical device drivers and virtual device drivers use the following OS/2 DevHlp functions to establish inter-device driver communication (IDC).

RegisterPDD This function is called by the PDD during initialization to advertise a 16:16 entry point for VDD-PDD communication. The PDD provides a textual name, which the VDD must supply during its initialization.

VDHOpenPDD This function gets the address of the routine in a physical device driver that the virtual device driver uses to communicate with the physical device driver. The physical device driver's device must have previously registered its name and entry point using the DevHlp service, RegisterPDD. If the function is successful, it returns a pointer to the physical device driver IDC entry point.





=== MAD16 PDD and VDD Sample Device Drivers (Watcom C) ===

The Developer Connection Device Driver Source Kit for OS/2 includes a PDD/ VDD pair that program the OPTi/MediaChips 82C928/82C929 Audio Controller ( MAD16). The MAD16 is an integrated digital audio controller for PC sound applications.

Beyond its use for multimedia device developers, the sample provides a reference for using Watcom 16 and 32-bit C compilers for OS/2 device driver development.

The device drivers are located on the CD-ROM in the multimedia section.

PDD \ddkx86\mmos2\samples\mad16

VDD \ddkx86\mmos2\samples\vmad16





=== Board Architecture ===

The reference design for the MAD16 includes the following primary parts:

<pre class="western">/-------------------------------------------------------------\
|Chip                     |Description                        |
|-------------------------+-----------------------------------|
|OPTi 82C929 (MAD16)      |Primary chip. ISA bus interface,   |
|                         |CD-ROM control, MPU-401 interface  |
|                         |and Sound Blaster to Windows Sound |
|                         |System command translation.        |
|-------------------------+-----------------------------------|
|Audio Codec              |Windows Sound System compatible    |
|                         |audio CODEC. The sample supports   |
|                         |the Analog Devices AD1848 and the  |
|                         |Crystal Semiconductor CS4231.      |
|-------------------------+-----------------------------------|
|Yamaha YMF-262 (OPL-3)   |FM MIDI synthesis (same part as    |
|                         |Sound Blaster Pro).                |
|-------------------------+-----------------------------------|
|CD-ROM connectors        |Support Sony31A, Mitsumi, IDE and  |
|                         |Panasonic drives.  All interfaces  |
|                         |are controlled via the MAD16.      |
\-------------------------------------------------------------/</pre>
The MAD16-based board can support applications and device drivers written to a variety of CD-ROM, audio and MIDI interfaces.





=== MAD16.ADD Device Driver Overview ===

All device configuration is performed through software programmable settings. Base I/O address and DMA and IRQ selections for CD-ROM and audio are initialized from software through the MAD16.ADD device driver. There are no jumpers.

Once enabled, existing device drivers can be used to perform audio and CD- ROM actions. For example, existing AD1848 business audio device drivers can be used on configurations with the AD1848. Existing CS4231 device drivers can be used in board configurations that have the CS4231 device. Likewise, the MAD16 device can be set to enable Sony31A, Mitsumi, Panasonic or IDE CD -ROM interfaces. An appropriate CD-ROM device driver is loaded later to perform CD-ROM activities.

The job of the MAD16.ADD is to initialize the device.





=== Boot Sequence ===

To initialize the device before the other device drivers load, the MAD16. ADD device driver has to load before the other device drivers (Audio/CD-ROM ). OS/2 loads device drivers in a specific order. Device drivers needed to boot the system are loaded early. Less critical device drivers including audio are loaded toward the end of the device driver load sequence. In a particular class of device drivers, load order is based on order in the CONFIG.sys.

Device driver load order is as follows:

1.Kernel known basedevs (resource manager) <br />2.BASEDEVs <br />a..ADDs first <br />b..SYS <br />3.Non-BASEDEVs (for example, Audio)

To load early, the MAD16.ADD wakeup code is written as a BASEDEV .ADD. This insures that regardless of CONFIG.SYS order, it loads early. For CD-ROM however, both the wakeup code and CD-ROM device driver are .ADDs. This creates an install requirement that the MAD16.ADD precede the CD-ROM device driver in CONFIG.SYS.





=== PDD Operation and Architecture ===

The MAD16.ADD does most of its work during initialization. Device modes and settings are read from a persistent database (CONFIG.SYS). The MAD16 device is programmed to set the base address of all the other parts on the board. For CD-ROM, turning the device on is all that is required. For audio, an initialization sequence is required to bring the audio Codec and MAD16 to a state where both Windows Sound System and Sound Blaster applications can be supported.

Using Watcom 16-bit C, the MAD16.ADD device driver has very little assembler code. The strategy routine is executed with no assembler stub. Watcom provides &quot;pragma aux &quot;, which allows the programmer to specify that parameters arrive in registers rather than on the stack. With this, much of the stub code popular in C device drivers is unnecessary.

The following table describes the MAD16.ADD source code.

<pre class="western">/-------------------------------------------------------------\
|MAD16.ADD Source Files   |Description                        |
|-------------------------+-----------------------------------|
|makefile                 |Build procedure - &quot;nmake&quot;.         |
|-------------------------+-----------------------------------|
|DATA.C                   |Device driver data (global).       |
|-------------------------+-----------------------------------|
|DDPRINTF.C               |Support for writing messages to    |
|                         |console (printf).                  |
|-------------------------+-----------------------------------|
|DDSTRING.C               |String processing routines (command|
|                         |line parsing support).             |
|-------------------------+-----------------------------------|
|HEADER.C                 |Device driver header (DevHdr).     |
|-------------------------+-----------------------------------|
|IDC_PDD.C                |IDC operations for PDDs.           |
|-------------------------+-----------------------------------|
|IDC_VDD.C                |IDC operations for VDDs.           |
|-------------------------+-----------------------------------|
|INIT.C                   |Initialization code (Good place to |
|                         |start reading).                    |
|-------------------------+-----------------------------------|
|IOCTL.C                  |IO Control processing (called from |
|                         |Strategy routine).                 |
|-------------------------+-----------------------------------|
|MAD16.C                  |Code that knows how to initialize  |
|                         |the 82C929 MAD16 device.           |
|-------------------------+-----------------------------------|
|MADUTIL.C                |Code that programs the MAD16       |
|                         |(retained after init).             |
|-------------------------+-----------------------------------|
|QMAD16.C                 |32-bit Application - display PDD   |
|                         |structures to screen.              |
|-------------------------+-----------------------------------|
|SNDBLAST.C               |Code that knows how to reset and   |
|                         |program a Sound Blaster Pro.       |
|-------------------------+-----------------------------------|
|STRATEGY.C               |Device driver strategy routine.    |
|-------------------------+-----------------------------------|
|TRACE.C                  |Holds trace information and copies |
|                         |of error messages.                 |
|-------------------------+-----------------------------------|
|UTIL.C                   |I/O delay function, OPL-3 mute     |
|                         |code.                              |
|-------------------------+-----------------------------------|
|WSS.C                    |Code that initializes the audio    |
|                         |CODEC.                             |
|-------------------------+-----------------------------------|
|WSSUTIL.C                |Audio CODEC code (retained after   |
|                         |init).                             |
|-------------------------+-----------------------------------|
|SEGS.ASM                 |Define device driver segments.     |
|-------------------------+-----------------------------------|
|UTILA.ASM                |IDC entrypoints (16:16 &lt;-&gt; 16:32   |
|                         |thunks).                           |
|-------------------------+-----------------------------------|
|DATA.H                   |Header file for DATA.C.            |
|-------------------------+-----------------------------------|
|DDPRINTF.H               |Header file for DDPRINTF.C.        |
|-------------------------+-----------------------------------|
|DDSTRING.H               |Header file for DDSTRING.C.        |
|-------------------------+-----------------------------------|
|HEADER.H                 |Header file for HEADER.C.          |
|-------------------------+-----------------------------------|
|IDC_PDD.H                |Header file for IDC_PDD.C.         |
|-------------------------+-----------------------------------|
|IDC_VDD.H                |Header file for IDC_VDD.C.         |
|-------------------------+-----------------------------------|
|IOCTL.H                  |Header file for IOCTL.C.           |
|-------------------------+-----------------------------------|
|MAD16.H                  |Header file for MAD16.C.           |
|-------------------------+-----------------------------------|
|REQPKT.H                 |Header file for REQPKT.C.          |
|-------------------------+-----------------------------------|
|RMHELP.H                 |Header file for RMHELP.C.          |
|-------------------------+-----------------------------------|
|SNDBLAST.H               |Header file for SNDBLAST.C.        |
|-------------------------+-----------------------------------|
|STRATEGY.H               |Header file for STRATEGY.C.        |
|-------------------------+-----------------------------------|
|TRACE.H                  |Header file for TRACE.C.           |
|-------------------------+-----------------------------------|
|UTIL.H                   |Header file for UTIL.C.            |
|-------------------------+-----------------------------------|
|WSS.H                    |Header file for WSS.C.             |
\-------------------------------------------------------------/</pre>




=== VDD Operation and Architecture ===

Because all audio operations are performed by the audio CODEC, only one audio mode can be active at one time. The device is not capable of performing two concurrent wave audio play operations.

At initialization, one mode must be selected. By convention, the Windows Sound System mode is the default because this support is used by MMPM/2 and WinOS2 for wave audio operations.

Becuase OS/2 and WinOS2 audio are controlled by the audio CODEC PDD, DRV, and VDD, the VMAD16 VDD must communicate with the other drivers to negotiate use of the audio device.

Audio operations are performed using existing audio device drivers. Sound Blaster games are supported in a virtual DOS machine through a OS/2 Virtual Device Driver (VMAD16).

The figure below illustrates the architecture.

<pre class="western">  /----------\  /----------\  /----------\ /-----------\ /-----------\
  |QMAD16.exe|  |MMPM/2    |  |WinOS2    | |DOS Session| |DOS Session|
  |Diagnostic|  |MME subsys|  |MME subsys| |WSS App    | |SB App     |
  \----------/  \----------/  |----------| \-----------/ \-----------/
       |             |        |Audio.DRV |      |             |
       | Ring-3      |        \----------/      |             |
  -----|-------------|--------------|-----------|-------------|-------
       | Ring-0      |              | /---------/             |
  /---------\     /---------\     /---------\            /---------\
  |MAD16.ADD|     |Audio PDD|-----|AudioVDD |            | VMAD16  |
  \---------/     \---------/     \---------/            \---------/
        |               \----------------------------------/  |
        \-----------------------------------------------------/</pre>
When a Sound Blaster specific application, such as a game, programs the device from a Virtual DOS machine, the VMAD16.SYS VDD intercepts the first port I/O and takes this as a request to use the audio hardware. It communicates with the audio CODEC PDD to gain ownership. Once ownership is attained, the VMAD16 VDD sends a command to the MAD16.ADD wakeup code commanding it to switch the device from Windows Sound System mode into Sound Blaster mode.

When the owning DOS application terminates, the VDD commands a switch back to Windows Sound System mode and returns device ownership to the audio CODEC PDD.

The following table describes the VMAD16.SYS source code.

<pre class="western">/-------------------------------------------------------------\
|VMAD16.SYS Source        |Description                        |
|-------------------------+-----------------------------------|
|makefile                 |Build procedure - &quot;nmake&quot;.         |
|-------------------------+-----------------------------------|
|DDSTRING.C               |String processing routines.        |
|-------------------------+-----------------------------------|
|EVENTS.C                 |Session create/terminate and other |
|                         |event hooks.                       |
|-------------------------+-----------------------------------|
|GLOBDATA.C               |VDD global data declarations.      |
|-------------------------+-----------------------------------|
|INIT.C                   |Initialization code.               |
|-------------------------+-----------------------------------|
|AUDIOREQ.C               |Routines to communicate with audio |
|                         |PDD for hardware ownership.        |
|-------------------------+-----------------------------------|
|DATA.ASM                 |Per DOS session instance data      |
|                         |declarations.                      |
|-------------------------+-----------------------------------|
|UTILA.ASM                |IDC support (16:32 to 16:16 far    |
|                         |calls).                            |
|-------------------------+-----------------------------------|
|AUDIOREQ.H               |Header for AUDIOREQ.C.             |
|-------------------------+-----------------------------------|
|AUDIOVDD.H               |Header for AUDIOVDD.C.             |
|-------------------------+-----------------------------------|
|DATA.H                   |Prototypes for GLOBDATA.C and      |
|                         |DATA.ASM.                          |
|-------------------------+-----------------------------------|
|DDSTRING.H               |Header for DDSTRING.C.             |
|-------------------------+-----------------------------------|
|EVENTS.H                 |Header for EVENTS.C.               |
|-------------------------+-----------------------------------|
|UTIL.H                   |Header for UTIL.C.                 |
\-------------------------------------------------------------/</pre>




=== PDD Sample for Video Capture Adapters ===

This DDK provides a sample of a video capture physical device driver (PDD) to assist in the creation of physical device drivers (PDDs) for video capture adapters (VCAs).





=== Source Code ===

Source code for the physical device driver (PDD) sample is located in the \ MMOS2\MMTOOLKT\SAMPLES\VCADDT subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines used in incorporating the module.

The sample programs require MASM** 5.1 for assembly.

<pre class="western">/-------------------------------------------------------------\
|File                     |Description                        |
|-------------------------+-----------------------------------|
|README                   |Describes how to create the        |
|                         |resource DLL containing the video  |
|                         |adapter information and how to     |
|                         |create the .SYS file containing the|
|                         |VCDD.                              |
|-------------------------+-----------------------------------|
|VCA32.ASM                |Contains the main entry point for  |
|                         |IOCtl parsing.                     |
|-------------------------+-----------------------------------|
|VCACAPT.ASM              |Contains image copy and scale      |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VCAIDC.ASM               |Contains device specific streaming |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VCAINIT.ASM              |Contains device initialization     |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VIDIDC.ASM               |Contains generic device streaming  |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VIDIDC.INC               |Contains streaming instances       |
|                         |structures.                        |
|-------------------------+-----------------------------------|
|VIDIN.INC                |Contains the open instance         |
|                         |structure.                         |
|-------------------------+-----------------------------------|
|VIDVCI.INC               |Contains the interface for the     |
|                         |IOCtl.                             |
|-------------------------+-----------------------------------|
|VIDVCIT.SYS              |Is the compiled device driver.     |
\-------------------------------------------------------------/</pre>




=== Program Flow ===

The following figure illustrates the program flow from the Media Device Manager (MDM) through the PDD and finally on to the video capture adapter.

<pre class="western">    /--------------\              /--------------\
    | Media Device | (4)          | SPI          |
    | Manager      |--------------� Interfaces   |
    |              |              | SSM          |
    \--------------/              \------�-------/
    (1)    |                      (5)    |
           |                             |
    /------�-------\              /------�-------\
    | Vendor-      |              | Video Capture|
    | Specific     |              | Stream       |
    | Driver       |              | Handler      |
    \--------------/              \------�-------/
    (2)    |                       (6)   |
           |                             |
    /------�-------\                     |
    | Physical     |                     |
    | Device       �---------------------/
    | Driver       |
    \--------------/
    (3)    |
           |
    /------�-------\
    | Video        |\ �-- Video Input
    | Capture      |/
    | Adapter      |
    \--------------/</pre>
1 Media Control Interface functions are passed from the MCD to the vendor- specific driver.

2 The VSD passes information to the PDD.

3 The PDD controls the video capture adapter. The sample provided works with the IBM VCA adapter. To modify the sample to work with a different adapter, you must replace all hardware-specific routines with routines that are specific to your adapter. If you update the PDD sample, make a backup copy first. In order for the generic install to work, you must update the RCDATA 12 parameters so that MINSTALL will install the correct PDD.

4 After the video capture adapter is initialized, the MCD passes control to the Video Capture Stream Handler through the SPI interface.

5 The SPI interface receives video data from the video capture stream handler.

6 The control video data from the Video Capture Stream Handler is passed to and from the PDD.





=== PDD Architecture ===

The following figure illustrates how the PDD fits in the overall MMPM/2 subsystem structure. The media device manager (MDM) uses Media Control Interface commands to pass information through the vendor-specific driver and on to the PDD. The PDD directly controls the video capture adapter and passed video adapter request to the video capture stream handler.

<pre class="western">        ÉÍÍÍÍÍÍÍÍ»                  /-------------\
        º        º                  | Multimedia  |
        º        º�--\              | Application |
        ÈÍÍÍÍÍÍÍÍ¼   |              \---�---------/
        PM Monitor   |    Notifications |     | MCI Commands
                     |           /------+-----+------\
                     |      /----+------------�------+----\
                     |      |    |        MDM        |    |
                     |      \----+-------------------+----/
                     |           |  /----------------+-------------------\
                     |    /-------------\     /------�--------\          |
           mmioOpen  \----|Digital Video|     |Amplifier Mixer|          |
     /--------------------|Media  Driver|-\ /-| Media  Driver |-----\    |
     |    mmioSetHeader   \-----�-------/ | | \--------�------/     |    |
     |                          |         | |          |            |    |
     |                          |   /-----�-�------\   |            |    |
     |                          |   |SPI Interfaces|   |            |    |
     |                          |   |--------------|   |            |    |
     |                          \---|     SSM      |---/            |    |
     |                              \-------------�/�--\            |    |
     |                               audio data   |    |            |    |
     |              /-----------\  /---------\    |  /-�-----\  /-------\|
/---------\mmioWrite|Multi-track�------------/�---+--|Audio  �--|Audio  ||
| MMIO    �---------|Stream     |  /-\            \\ |Stream |  |Adapter||
| Manager |mmioSeek |Handler    �--+-|             | |Handler|  \-------/|
\---------/         \-----------/  |-| uncompressed| \-------/       /---/
multi|track data/---\   compressed |-| /---------\ \�/-------\  /----�--\
/----�----------+-\ |         data |-| \---------/�--|Video  |  |Capture|
|   AVI         | | |              \�/  |   data     |Capture�--|DD     |
|   IOProc      | | |               |   |            |Stream |  |copy   |
\---------------+-/ |               |   \-----\      |Handler|  |scale  |
 | /------------+-\ |               |         |      \-------/  \-------/
 | | Ultimotion | | |               |   /-----�-------\         /---�---\
 | | RT Codec   | | |               \---| Compression |         |Video  |
 | \------------+-/ \-------------------| Stream      |         |Adapter|
 �              \-----------------------� Handler     |         \-------/
raw data               compression      \-------------/</pre>




=== Strategy Commands ===

There are several generic strategy commands that are supported by all physical device drivers, video or otherwise. These are documented in the ''OS /2 Physical Device Driver Reference''. The generic strategy commands supported by video device drivers are described in the following table.

<pre class="western">/------------------------------------------\
|Functions  |Description                   |
|-----------+------------------------------|
|INIT       |Initializes the device.       |
|-----------+------------------------------|
|OPEN       |Opens an instance of the      |
|           |device and prepares it for    |
|           |use.                          |
|-----------+------------------------------|
|CLOSE      |Closes an instance of the     |
|           |device.                       |
\------------------------------------------/</pre>




=== PDD Sample for MPEG Video Playback Devices ===

The Developer Connection Device Driver Source Kit for OS/2 provides a sample MPEG Video Playback physical device driver (PDD) to assist in the creation of PDDs for other video playback devices. This sample provides a code base for a new PDD, simplifies development, and illustrates the OS/2 MPEG Video Playback PDD model for a nonshared frame buffer device, also referred to as an overlay device. The ReelMagic card from Sigma Designs, Inc. is an example of such a device.

The code contained in this sample was derived from a working driver. All hardware-specific code and header files have been removed from the sample. Although this device driver was written for a device that uses the split- stream model, it is easily adaptable to the single-stream model.

The split-stream MPEG I/O procedure splits the audio and video packets out of the MPEG file. The audio data packets are passed through the subsystem to the audio DD, and the video data packets are passed through the subsystem to the video DD. As the audio DD returns the buffers that it has played, it also returns the current audio time-which is in turn passed through the subsystem to MPEG hardware compressor/decompressor (CODEC) and from there is sent to the video DD on the next VCAI_PLAY command.

The single-stream MPEG I/O procedure reads the entire MPEG file one buffer at a time-without splitting the video and audio data. As each buffer is read in, it is passed through the subsystem to the video DD. With single stream, every byte in the file is passed to the DD; whereas with split stream, only the video data packets are passed to the video DD. The single- stream video DD and its hardware are then responsible for producing the video and audio along with all synchronization.

'''Note:'''From the video DD's perspective, the main difference in the single- stream model is that the SCR, PTS, and Audio PTS fields in the VCAI_PLAY contain zero.





=== Source Code ===

Source code for the PPD sample is located on the Developer Connection Device Driver Source Kit for OS/2 CD-ROM. Source files include documented headers, which provide detailed descriptions of the programming concepts and routines.

<pre class="western">/-------------------------------------------------------------\
|File                     |Description                        |
|-------------------------+-----------------------------------|
|MAKEFILE                 |Makefile.                          |
|-------------------------+-----------------------------------|
|INIT.ASM                 |Handles the Device Init message at |
|                         |OS/2 start-up time.                |
|-------------------------+-----------------------------------|
|IOCTL.ASM                |IOCtl message routing and IOCtl    |
|                         |processing.                        |
|-------------------------+-----------------------------------|
|SUBSA.ASM                |Device-specific Assembler routines.|
|-------------------------+-----------------------------------|
|VEND.C                   |Device-specific C routines.        |
|-------------------------+-----------------------------------|
|VIDRMS1.INI              |Device-specific .INI (defaults     |
|                         |settings) file.                    |
|-------------------------+-----------------------------------|
|VIDVCI.INC               |IOCtl interface description/header |
|                         |file.                              |
|-------------------------+-----------------------------------|
|ENDOF.ASM                |Label to mark the end of the code. |
|-------------------------+-----------------------------------|
|INOUTP.C                 |C-callable routines for port IN and|
|                         |OUT.                               |
|-------------------------+-----------------------------------|
|INOUTP.H                 |C interface header file for Port IN|
|                         |and Port OUT routines.             |
|-------------------------+-----------------------------------|
|VIDVCI.H                 |IOCtl interface description/header |
|                         |file for .C.                       |
|-------------------------+-----------------------------------|
|VIDVCI.INC               |IOCtl interface description/header |
|                         |file for .ASM.                     |
|-------------------------+-----------------------------------|
|ARUNTIME.ASM             |Standard C runtime routines written|
|                         |in assembler.                      |
\-------------------------------------------------------------/</pre>




=== Program Flow ===

1.The application opens the MPEG Digital Video Device through the media control interface (MCI).

2.The media control device (MCD) finds the ''PDDname''and ''VSDname''in the MMPM2.INI file and opens the VSD with the ''PDDname''.

3.The VSD opens the PDD, reads in an .INI file, and passes the .INI file to the PDD. The filename is based on the first seven characters of the ''PDDname''with the .INI extension. The .INI file is device-dependent. The types of information in the .INI file may include default key color, video alignment offsets, and video quality adjustments.

4.Through the DevInfo IOCTL, the VSD queries the PDD to determine its capabilities.

5.The application loads an MPEG file through the MCI.

a.Through the standard I/O Proc interfaces, the MCD identifies MPGIO as the I/O Proc for the MPEG file.

b.Through the standard compressor/decompressor (CODEC) interfaces, the MPEG I/O Proc (MPEGIO) selects the MPEG hardware decompressor (MPEGDC). The MCD tells the VSD handle to the MPEGDC so that it can call the VSD/PDD to play back the compressed Video MPEG data.

c.Through the VSD and the PDD, the hardware CODEC MPEGDC loads the device with its DSP/MicroCode from a file whose name matches the results of a query of the VSD/PDD.

d.The MCD opens the playback window, queries the VSD/PDD for the transparent/key color, and paints the window with the key color.

e.The MCD tells the VSD/PDD the source movie size and window location.

f.The MCD tells the VSD/PDD to enable the monitor window and color keying.

6.The application issues a play command through the MCI.

7.The MPEG I/O Proc reads part of the MPEG file.

8.The audio data is sent through the system to the audio PDD.

'''Note:'''MPEG audio data is passed to the audio device driver via the DDCMD_ READWRITE_PARM structure. Field ulParm1 contains the initial audio system clock reference (SCR), and ulParm2 contains the Presentation Time Stamp ( PTS).

9.The video data is sent through the system to the MPEG CODEC (MPEGDC). If this data is the first packet in the stream, MPEGDC will issue a VCA_ PlayStart IOCtl to the VSD/PDD to set up the device and initialize the stream time. As the data arrives, MPEGDC issues a VCA_PlayData IOCtl to the VSD/PDD.

10.As the audio PDD plays audio buffers, it reports back to the audio stream time, which is eventually sent to MPEGDC.

11.The audio time is passed on the next VCA_PlayData IOCtl to the VSD/PDD.

'''Note:'''When playing from the beginning of an MPEG file the audio time will begin at zero regardless of the files initial SCR value.

12.Steps 7 through 11 are repeated until the end of the MPEG data/file is reached-at which time, a VCA_PlayStop is issued indicating that the end of the file has been reached.





=== Audio and Video Synchronization (Split-Stream Model) ===

The MPEGDC is a decompressor that does not require the MMPM/2 subsystem to control or time the flow of images to the decompressor, whereas the Ultimotion CODEC allows the MMPM/2 subsystem to control the flow of images to the decompressor, which is not called until it is time to display the image. Data is sent to MPEGDC as fast it can be sent by the system. The PDD and its hardware must control the synchronization between audio and video. When the data is arriving too fast (the hardware data buffers are filled), the PDD must suspend processing on the MPEGDC thread until the hardware can accept more data. The hardware may contain over three-fourths of a second of video data waiting to be decompressed. The hardware will decompress the image when its SCR reaches the presentation time stamp (PTS) of the data packet in the hardware buffer. If the SCR is greater than the PTS, the hardware will speed up or skip images until the PTS and SCR match.

To synchronize the audio with the video, the PDD must know the current audio time. Because the audio and video have separate hardware with different clocks, the video PDD will need the audio time to keep the video synchronized with the audio.

As the audio stream plays the audio buffer, it reports back the current audio time. This time is relayed to the MPEGDC. The MPEGDC will pass down the last reported audio time to the PDD on the VCA_PlayData IOCtl. To get the current audio SCR, the PDD multiplies the audio time by 30 to convert from MMTime to the MPEG 90KHz clock and adds the stream's initial SCR from the VCA_PlayStart IOCtl audio time. The PlayStart audio time is the initial stream SCR. It is required because the audio stream times reported by the audio subsystem are zero-based times and the PTSs in the video stream are based on the initial SCR. The PDD compares the hardware video SCR with the calculated audio SCR to determine if the video is ahead of or behind the audio. If the audio is not synchronized with the video hardware, the video SCR must be updated to match the audio SCR.

'''Note:'''The audio time may contain the same value on subsequent PlayData commands until the audio device driver updates the audio stream time. The audio time can be set to zero, meaning no audio in the MPEG file or no audio PDD. In either case, the audio and video synchronization logic may be skipped.





=== Running the Sample Device Driver ===

The easiest way to install and run this sample device driver is to install Sigma Designs' ReelMagic through the OS/2 Warp Selective Install and copy this sample device driver over the Sigma Design Reel Magic device driver that has the same name. The file can be found in the MMOS2 subdirectory ( usually \MMOS2\VIDRMS1.SYS).

This device driver will not display images on the screen because it contains no hardware-specific code, but it will allow you to see and follow the commands and data to the device driver.

Reboot the computer after installing this sample device driver.





=== Audio Sample for Vendor-Specific Drivers ===

OS/2 Warp, Version 3 provides sample files that assist in the creation of vendor-specific drivers (VSDs). The VSD defines a generic device driver- like interface that effectively decomposes high-level media control interface functions into more fundamental operations at the DLL level.

'''Note:'''VSD functionality is available for OS/2 Warp, Version 3 and is not downward compatible.

The following figure illustrates the program flow from the Media Device Manager (MDM) through the VSD and finally on to the audio adapter.

<pre class="western"> [Artwork not shown] </pre>


1 Media Control Interface functions are passed from the Media Device Manager to the vendor-specific driver using VSD commands.

2 The VSD passes information to its device driver. This provides a Ring-3 interface to control audio devices. The VSD sample provided with the DDK should be adequate to cover all basic audio functions. If your audio adapter requires special processing, you might have to supplement the sample VSD. To install the VSD, update the VSDDriver= option in the generic install routines (or CARDINFO.RC).

3 The device driver controls the audio adapter.

4 After the audio adapter is initialized, the MDM passes control to the Audio Stream Handler through the SPI interface.

In order to play or record audio data, the audio stream handler sends VSD_ DDCMD messages to the VSD.

5 The SPI interface sends/receives audio data from the audio stream handler .

6 The Audio Stream Handler controls audio data passed to and from the VSD.

7 The VSD reports stream events (such as buffer completion) via the SHC_ REPORT_INT message.





=== Source Code ===

Source code for the vendor-specific driver (VSD) sample is located in the ''IBM Device Driver Source Kit for OS/2''. Source files include documentation headers that provide detailed descriptions of the programming concepts and routines used in incorporating the sample.



<pre class="western">/-------------------------------------------------------------\
|AUDIOIF.C                |This module checks for valid VSD   |
|                         |messages and routes them to the    |
|                         |appropriate function. It also      |
|                         |performs flag checking and error   |
|                         |reporting.                         |
|-------------------------+-----------------------------------|
|VSDOPEN.C                |This module retrieves the          |
|                         |VSD_AUDIOOPEN_PARMS structure from |
|                         |the VSD_OPEN message, checks to see|
|                         |if the hardware supports the       |
|                         |requested mode and returns resource|
|                         |management information. VSDs should|
|                         |not allocate hardware resource on  |
|                         |the message. This will happen on   |
|                         |the VSD_RESTORE message.           |
|-------------------------+-----------------------------------|
|VSDSET.C                 |The source file processes the      |
|                         |following VSD_SET messages:        |
|                         |VSD_SETVOLUME                      |
|                         |Changes the volume for the current |
|                         |instance.                          |
|                         |VSD_SETCONNECTOR                   |
|                         |Enable/Disables connectors.        |
|                         |VSD_SETMIXCONNECTIONS              |
|                         |Connects a source to a sink.       |
|                         |VSD_SETAUDIOATTRIBUTES             |
|                         |Sets audio items such as treble,   |
|                         |bass etc.                          |
|                         |VSD_SETMONITOR                     |
|                         |Enables/disables audio monitoring. |
|                         |VSD_SETDATATYPE                    |
|                         |Sets mode (i.e. bits/sample,       |
|                         |channels, sampling rate etc.).     |
|                         |VSD_SETMIXCONTROL                  |
|                         |Sets the attributes for a mixer    |
|                         |line.                              |
|-------------------------+-----------------------------------|
|VSDMAN.C                 |Processes the following messages:  |
|                         |VSD_RESTORE                        |
|                         |Consumes hardware resources. On    |
|                         |some audio cards, it will also load|
|                         |a DSP.                             |
|                         |VSD_SAVE                           |
|                         |Removes hardware utilization (other|
|                         |instances can use it after it is   |
|                         |done).                             |
|                         |VSD_CLOSE                          |
|                         |Closes VSD and frees memory etc.   |
|                         |VSD_RESOURCE                       |
|                         |Returns resource management        |
|                         |information to the caller.         |
|-------------------------+-----------------------------------|
|VSDIOCTL.C               |This C module makes AUDIODD IOCTL  |
|                         |calls. See the AUDIODD reference   |
|                         |for more information.              |
|-------------------------+-----------------------------------|
|VSDCAP.C                 |Processes the VSD_GETDEVCAPS       |
|                         |message. Returns the capabilities  |
|                         |of the VSD to the caller.          |
|-------------------------+-----------------------------------|
|VSDQUERY.C               |Processes the following messages:  |
|                         |VSD_QUERYVOLUME                    |
|                         |Returns the current volume setting.|
|                         |VSD_QUERYCONNECTOR                 |
|                         |Returns the state of a hardware    |
|                         |connector.                         |
|                         |VSD_QUERYMIXCONNECTIONS            |
|                         |Returns the source/sink connection |
|                         |information.                       |
|                         |VSD_QUERYAUDIOATTRIBUTES           |
|                         |Returns the status of audio        |
|                         |attributes.                        |
|                         |VSD_QUERYMONITOR                   |
|                         |Returns if audio monitoring is     |
|                         |available.                         |
|                         |VSD_QUERYDATATYPE                  |
|                         |Returns if a particular datatype is|
|                         |supported in the VSD.              |
|                         |VSD_QUERYMIXCONTROL                |
|                         |Returns the status of audio        |
|                         |attributes for a mixer sink/source.|
|                         |VSD_QUERYMIXLINE                   |
|                         |Returns line capabilities.         |
|-------------------------+-----------------------------------|
|VSDCONN.C                |Handles AUDIODD input/output       |
|                         |connections.                       |
|-------------------------+-----------------------------------|
|VSDDEF.C                 |Processes shared memory for the    |
|                         |VSD.                               |
|-------------------------+-----------------------------------|
|VSDINI.C                 |This file reads a vendor specific  |
|                         |initialization file, determines    |
|                         |resource management information to |
|                         |be returned on VSD_OPEN or         |
|                         |VSD_QUERYDATATYPE.                 |
|-------------------------+-----------------------------------|
|OS2MIXER.C               |Processes AUDIODD mixer IOCtls. For|
|                         |more information, see Mixer IOCtl  |
|                         |Functions Introduction.            |
|-------------------------+-----------------------------------|
|VSDINI2.C                |Main entry point.                  |
|-------------------------+-----------------------------------|
|DDCMD.C                  |Processes streaming related        |
|                         |functions. Communicates with       |
|                         |protect mode device driver to      |
|                         |implement DDCMD processing.        |
\-------------------------------------------------------------/</pre>




=== VSD Architecture ===

The VSD layer is a device-independent physical device driver-like layer that resides in Ring 3. It passes information between the media control interface subsystem and multimedia devices. [Artwork not shown] A VSD has the following characteristics:

�Does not deal with media control interface notifications. <br />�Usually uses a single standard time format (milliseconds). <br />�Usually does not have to deal with file management.





=== Interface to the VSD ===

The interface to the Vendor Specific Driver (VSD) uses an entry point called [[00235.htm|VSDEntry]]. First a DosLoadModule is issued for the VSD's DLL. The DosLoadModule returns a handle for the VSD. Then with the VSD handle, a DosQueryProcAddr is issued to find the VSD entry point (VSDEntry). From this point on, calls to the VSD are made through the following API:

<pre class="western">ULONG    VSDEntry ( HVSD       hvsd,     // Handle to VSD driver
                    ULONG      ulFunc,   // Function code
                    ULONG      ulFlags,  // Flags for driver
                    PVOID      pRequest) // Request Parameter Block/Value</pre>




=== Events ===

When the VSD receives VSD_DDCMD with [[00779.htm|DDCMDREGISTER]], it should store the ''hid'' , ''hStream'', and ''pSHDEntryPoint''fields of the [[00779.htm|DDCMDREGISTER]]structure for use in reporting events. To report an event, the VSD should use the function pointer from the register to call the stream handler.





=== VSD_DDCMD ===

DDCMD_STOP (see the ''ulCmd''field of the [[00759.htm|DDCMDCONTROL]]structure) operates differently for VSDs than for physical device drivers.

When a PDD receives a DDCMD_STOP, it is assumed that the stop is completed.

When a VSD receives a DDCMD_STOP, the stop is not considered complete when it is returned from the call. Rather it is considered complete when it the VSD is sent a STREAM_STOP_NOW (see ''ulFlag''of the [[00966.htm|SHD_REPORTINT]]structure and ''ulFlag''of the [[00946.htm|MSG_REPORTINT]]structure.)

'''Note:'''VSDs will receive [[00255.htm|VSD_DDCMD]]in the ''ulFunc''parameter of the [[00235.htm|VSDEntry]]. To process specific VSD_DDCMDs, you must examine the ''pRequest''parameter.

The following code sample shows how this can be written.

<pre class="western">LONG APIENTRY mixerDDCMDEntryPoint(  HVSD   hvsd,
                                     ULONG  ulFunc,
                                     ULONG  ulFlags,
                                     PVOID  pRequest )
{

  PDDCMDCOMMON  pCommon = (PDDCMDCOMMON) pRequest;

  if (pCommon == NULL)
  {
          return (ERROR_INVALID_BLOCK) ;
  }

  switch (pCommon-&gt;ulFunction)
  {
          case DDCMD_SETUP:
                return DDCmdSetup ((PDDCMDSETUP)pCommon, (PMCI_AMP_INSTANCE)hvsd );

          case DDCMD_READ:
                return DDCmdRead ((PDDCMDREADWRITE)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_WRITE:
                return DDCmdWrite ((PDDCMDREADWRITE)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_STATUS:
                return DDCmdStatus ((PDDCMDSTATUS)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_CONTROL:
                return DDCmdControl ((PDDCMDCONTROL)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_REG_STREAM:
                return DDCmdRegister ((PDDCMDREGISTER)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_DEREG_STREAM:
                return DDCmdDeRegister ((PDDCMDDEREGISTER)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          default:
                return (ERROR_INVALID_FUNCTION);
  }
}</pre>




=== Communication to the Stream Handler ===

The [[00212.htm|SHDEntryPoint]]contains the following two messages. These messages are located in the SHDD.H file of the \MMOS2\MMTOOLKT\H subdirectory. SHDD.H contains the data structures, their type definitions, and #define statements for certain values. Note that the messages pass pointers to packets of data, to allow maximum flexibility for the future.

SHC_REPORT_INIT The VSD uses this message when it needs data at interrupt time. For example, it uses this message to tell the stream handler that it has used up all the data and needs more.

When the stream handler gets the call, it knows the VSD is passing back a buffer that it might already have consumed. So the stream handler returns on that call, giving the VSD a fresh buffer to consume.

'''Note:'''It is possible for the stream handler to call back into the VSD when the stream handler receives an shc_report_init.

SHC_REPORT_EVENT The stream handler uses this message to keep in sync with VSD activities. For example, the stream handler can request the VSD to report back every tenth of a second that data is played. The stream handler has all the logic to handle these events. The VSD examines the request, and during its checks when it realizes a tenth of a second has been played in data, the VSD calls SHD_REPORT_EVENT. The stream handler can do what it wants at this point, and the VSD returns.

The VSD keeps track of the processes. In other words, only the VSD knows how much data, to the millisecond, has been played out to the device. The stream handler can approximate the data played, using calculations based on how much data has gone by. But the stream handler cannot calculate the data played to the millisecond, or even to the fraction of a millisecond, the way the VSD can.





=== Stream Handler Values ===

There are certain values that the stream handler is expecting. For example , when the stream handler requests a stop or a pause on a [[00162.htm|DDCMD_CONTROL]]message, the pointer that comes back to the stream handler is a pointer to the cumulative time that the VSD has recorded in real time. So whenever the stream handler requests the device to stop, the VSD honors that request and informs the stream handler the real time that the VSD stopped within the stream.

Another value the stream handler looks for is returned on [[00197.htm|DDCMD_STATUS]]. This is also a pointer to the cumulative time from the VSD, with respect to when that stream was first started at the stream handler's request.





=== VSD Values ===

The stream handler passes a pointer to the VSD on [[00197.htm|DDCMD_STATUS]]. This points to a value used by the VSD for setting the referenced time of the VSD. It is not always correct for the VSD to start its time at 0 every time the stream handler does a start, because the stream handler might have performed a seek in the stream. The VSD might have played a minute of data and then performed a backwards seek to the 30-second mark in the data. If a start is issued, the VSD should start from the 30-second mark in that stream.

[[00162.htm|DDCMD_CONTROL]]has an important NOTIFY subfunction that is used for cuepoint or event detection. The stream handler supports events in cuepoints-an application request to be notified when a particular location in the file is reached or a specific time period has elapsed. The stream handler uses two methods for detecting how much time has elapsed:

�Using DDCMD_CONTROL NOTIFY, the stream handler requests to be notified by the VSD at a particular time and passes a pointer to the cue time.

�The stream handler determines the time internally. This method is not as precise as the first method, because only the VSD knows the real time.

For example, suppose the stream handler does a DDCMD_CONTROL NOTIFY at one minute. If the VSD supports precise event detection, it must accept this request and put it into a queue somewhere, preferably a linked list. This linked list will have the time of one minute so that during the streaming process, the VSD occasionally checks to see whether it is at the one minute mark. When this event occurs, the VSD calls back on an [[00220.htm|SHD_REPORT_EVENT]]. Then you can free up the event detection linked list node.

Keep in mind that the VSD should have the capability to queue these requests because there might be additional requests. For example, an application might request to be notified at the one-minute mark, next at a minute and a half, and possibly every five minutes.

If the VSD does not support event detection, then when it gets called on a DDCMD_CONTROL NOTIFY, it responds with an ERROR_INVALID_REQUEST. This response tells the stream handler that it must do the event-detection itself.





=== Priorities ===

When the VSD receives [[00176.htm|DDCMD_READ]]and [[00204.htm|DDCMD_WRITE]]messages, it will occur on a time-critical thread from the audio stream handler. If other threads are running, the DDCMD thread will always run first because of priority.

Other commands such as [[00424.htm|VSD_SET]]and [[00300.htm|VSD_QUERY]]may come simultaneously at a normal priority. (You may be executing one command and then be jumped to a thread of higher priority.)





=== Device Type Function Table ===

Because the VSD interface supports commands for numerous data types, it is not necessary for every VSD to support all commands. The only commands that must be supported are those for the particular device type (for example, audio, video, and so on) that the VSD is implementing. This section provides guidelines for which functions and flags must be supported and which functions and flags are optional. The following table shows which functions are Required (R) and Optional (O) by device type.

<pre class="western">/------------------------------------------------------------------\
|Functions/Subfunctions            |Digital|Amp    |Laser  |Fax/Tam|
|                                  |Audio  |Mixer  |Disk   |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_CLOSE                         |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_GETDEVCAPS                    |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_OPEN                          |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_RESOURCE                      |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_RESTORE                       |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_SAVE                          |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERY                         |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_SET                           |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_ESCAPE                        |O      |O      |O      |O      |
\------------------------------------------------------------------/</pre>


<pre class="western">Legend:
  R - Required Command 
  O - Optional Command </pre>
The flags that must be supported by a VSD for the VSD_SET command vary according to the media types it supports. The following table illustrates which flags are required for the specified media type.

<pre class="western">/------------------------------------------------------------------\
|Functions/Subfunctions            |Digital|Amp    |Laser  |Fax/Tam|
|                                  |Audio  |Mixer  |Disk   |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETVOLUME                     |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETAUDIOATTRIBUTES            |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETMONITOR                    |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETDATATYPE                   |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETCONNECTOR                  |       |       |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETMIXCONNECTIONS             |       |       |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETMIXCONTROL                 |       |       |       |       |
\------------------------------------------------------------------/</pre>


<pre class="western">Legend:
  R - Required Command 
  O - Optional Command 
  &lt;Blank&gt; - Not Applicable </pre>
The flags that must be supported by a VSD for the VSD_QUERY command vary according to the media types it supports. The following table illustrates which flags are required for the specified media type.

<pre class="western">/------------------------------------------------------------------\
|Functions/Subfunctions            |Digital|Amp    |Laser  |Fax/Tam|
|                                  |Audio  |Mixer  |Disk   |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYCONNECTOR                |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYDATATYPE                 |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMONITOR                  |       |O      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYVOLUME                   |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMIXCONNECTIONS           |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMIXCONTROL               |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMIXLINE                  |       |R      |       |       |
\------------------------------------------------------------------/</pre>


<pre class="western">Legend:
  R - Required Command 
  O - Optional Command 
  &lt;Blank&gt; - Not Applicable </pre>




=== Device States ===

Media devices that transport data are considered to be in one of the following states at any given time:

�Registered <br />�Deregistered <br />�Saved <br />�Restored <br />�Closed

When a device is opened and restored, the device context is assumed to be in the ''restored''state. The ''closed''state can be viewed as both the initial state and the termination state. Or this state can be thought of as not a state at all, because a device context does not exist before it is opened, and ceases to exist when it is closed.

The following figure lists the allowable device states across the top of the table and indicates the changes in state that occur when the command messages shown in the first column of the table are issued. This table assumes all error conditions keep the device in its current state. For example, a waveform player that is opened without an element remains in the stopped state when a play is issued, and the MCD receives an error code.

The following figure is provided as a guide to application developers and MCD writers. There can be no guarantee that every media device will conform to this table, but every effort should be made to hide the complexity of the device from the application.

[Artwork not shown]

'''Legend'''

* After a restore, the device is considered active and available for use. If the stream has been registered, it is restored to the state it was in before the VSD_SAVE. <br />- Error condition.





=== Install ===

To manually install the VSD, change the VSDDRIVER= statement for the relevant amp-mixer device to the new DLL name. To permanently install the VSD, see [[00006.htm|Adding Support for Audio and Video Adapters]].





=== Using the High-Resolution Timer ===

The high-resolution timer (HRT) is used to provide millisecond-accuracy timing services to device drivers and applications.





=== Introduction ===

The high-resolution timer package includes the following files:

TIMER0.SYS the high-resolution timer driver

CLOCK01.SYS a modified CLOCK01.SYS for high-resolution timer support

CLOCK02.SYS modified CLOCK02.SYS for high-resolution timer support

TMR0_IDC.H the header file used to communicate with the high-resolution timer from another PDD

TMR0_IOC.H the header file for IOCtl interface to the high-resolution timer

TIMER0.DDP the DDINSTAL installation script





=== Installation ===

To install the high-resolution timer device driver, follow these steps:

1.Remove the readonly attribute from \OS2\BOOT\CLOCK*.SYS with the attrib command, e.g.:

<pre class="western">-r \os2\boot\clock*.sys</pre>
where * is the number in the name of your existing clock-system file. <br />2.Make a backup of \OS2\BOOT\CLOCK*.SYS. <br />3.Use DDINSTAL to install the driver. <br />4.Reboot.

'''Note:'''The high-resolution timer is intended for use with OS/2 Warp 3.0 and later. It has not been tested and is not supported under any previous version of OS/2. If you do use this timer with any previous version of OS/2 , you do so at your own risk.





=== Information for Microsoft C 6.0 Users ===

The header files were designed for Watcom C/C++ 10.0. If you are using Microsoft C 6.0, the only change that should be needed is to change the __ far, __cdecl, and __loadds keywords to _far, _cdecl, and _loadds-i.e., replace the double underscores with single underscores. To date, however, this has not been verified.





=== Ring-0 Usage ===

The high-resolution timer provides the following two services:

callback every ''n''milliseconds where ''n''is an integer &gt;= 1. This first option allows your device driver to register itself with the high-resolution timer . The device driver provides a 16:16 address of a function that the high- resolution timer calls every ''n''milliseconds. Registration (and deregistration) cannot occur during interrupt time.

If a device driver re-registers itself-by calling the registration function with the same 16:16 pointer-the high-resolution timer simply changes the count. This can occur at interrupt time.

query the current time This second option is used to obtain a 16:16 pointer to the current count variable. This variable can then be read by the device driver to obtain the current time. Note that this variable is only updated if the high-resolution timer is active-which is only true if at least one driver or application has registered itself with the high-resolution timer. Also note that this variable can be synchronized to another timeclock.

To call the high-resolution timer, call DevHelp_AttachDD with the first parameter as &quot;TIMER0$ &quot;. Remember, DDTable must be allocated in the default data segment. If you make it a local non-static variable (i.e., it is on the stack), the DevHelp_AttachDD call will fail. For example:

<pre class="western">TIMER0_ATTACH_DD DDTable;
PTMRFN ptmrfn;

DDTable.pfn=NULL;
if( DevHelp_AttachDD( ( NPSZ ) &quot;TIMER0$ &quot;, ( NPBYTE )  &amp;DDTable ) )
{
    // TIMER0.SYS not loaded
}

if( !DDTable.pfn )
{
    // Something wrong with TIMER0.SYS
}

ptmrfn=DDTable.pfn;</pre>


To register your driver with TIMER0.SYS, do something like this:

<pre class="western">#define N    10                              // Call me every N milliseconds

void __far __loadds InterruptHandler( void )
{
   // This function is called every N milliseconds
}

if( ptmrfn( TMR0_REG, ( ULONG ) InterruptHandler, N ) )
{
   // Registration failed
}</pre>


A ptmrfn() call '''must'''occur at ring 0. This means that it cannot be made from your strategy INIT routine. The DevHelp_AttachDD call can be made from the INIT routine.

The ptrmfn() call cannot be made from INIT COMPLETE either. Attempts to do so will result in a return code of 6.





=== Ring-3 Usage ===

The IOCtl interface provides the ability to:

obtain a pointer to the clock counter The pointer returned is a 16:16 pointer, which should be converted to a 0:32 pointer for use with 32-bit applications.

query and set the resolution Currently, the resolution is always 1 millisecond. Attempts to set it to another value will be ignored, and querying the driver will always return 1 millisecond. You should set the resolution anyway-in the future, the driver may actually use a lower resolution to conserve resources.

block until a certain time has elapsed

Use the following code as an example of reading the current time. The compiler used is C-Set++ 2.1. If you use a different compiler, you may need another technique for handling 16:16 pointers.

<pre class="western">#include &quot;tmr0_ioc.h&quot;

APIRET rc;
HFILE  hfile;
ULONG  ulAction;
ULONG  ulOpenFlag = OPEN_ACTION_OPEN_IF_EXISTS;
ULONG  ulOpenMode = OPEN_FLAGS_FAIL_ON_ERROR |
                    OPEN_SHARE_DENYNONE |
                    OPEN_ACCESS_READWRITE;

ULONG  ulResolution = 1;
ULONG  ulSize1=sizeof( ulResolution );

ULONG  * _Seg16 pulTimer16;
ULONG  ulSize2=sizeof( pulTimer16 );
ULONG  *pulTimer;</pre>


<pre class="western">rc=DosOpen( &quot;TIMER0$ &quot;, &amp;hfile, &amp;ulAction, 0, 0, ulOpenFlag, ulOpenMode, NULL );
if( rc )
{
   printf( &quot;Couldn't open TIMER0$.\n&quot; );
   return;
}

printf( &quot;TIMER0$ opened.  File Handle is %lu\n&quot;,hfile );</pre>


<pre class="western">rc=DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_SET_RESOLUTION,
                &amp;ulResolution, ulSize1, &amp;ulSize1, NULL, 0, NULL );
if( rc )
{
   printf( &quot;Couldn't set resolution.\n&quot; );
   DosClose( hfile );
   return;
}</pre>


<pre class="western">rc=DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_GET_POINTER,
                NULL, 0, NULL, &amp;pulTimer16, ulSize2, &amp;ulSize2 );
if( rc )
{
   printf( &quot;Couldn't get pointer.\n&quot; );
   DosClose( hfile );
   return;
}

pulTimer=pulTimer16;                // Converts a 16:16 pointer to a 0:32 pointer
if( !pulTimer )
{
   printf( &quot;NULL pointer.\n&quot; );
   DosClose( hfile );
   return;
}

// At this point, pulTimer is now a pointer to the timer 0 counter variable

rc=DosClose( hfile );</pre>


DosOpen( &quot;TIMER0$&quot; ) registers the application as a client. At this point, the high-resolution timer driver is taking interrupts; so make sure the driver is open only when you need timer services. The pointer is valid for the life of the process; and each call to HRT_GET_POINTER allocates another selector-therefore, this call should be made only once.

To block until a certain time has elapsed, use the following code as an example. For brevity, the details (such as checking return codes) have been omitted.

<pre class="western">ULONG  ulDelay=1;                     // Number of milliseconds to wait
ULONG  ulSize2=sizeof( ulDelay );

DosOpen( &quot;TIMER0$  &quot;, &amp;hfile, &amp;ulAction, 0, 0, ulOpenFlag, ulOpenMode, NULL );
DosSetPriority( 0, PRTYC_TIMECRITICAL, 0, 0 );
DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_BLOCKUNTIL,
             &amp;ulDelay, ulSize2, &amp;ulSize2, NULL, 0, NULL );</pre>


Using a time-critical thread is important.





=== Common Problems ===

The following problems might occur due to the nature of the high-resolution driver.

trap D This is usually caused by using the wrong version of CLOCK0x.SYS. If the old CLOCK0x.SYS is in \OS2, for example, and the new one is in \OS2\ BOOT, the kernel will load the old driver. A quick way to check is to use the command &quot;dir \clock0?.sy? /s&quot; on the boot partition. This will search the entire hard drive for the clock drivers.

clock driver will not load Either some performance tool is running, or you are using the Warp GA version of CLOCK0x.SYS.





=== Caveats ===

The following should be considered when using the high-resolution timer:

�Only the first parameter to PTMRFN is checked; no other parameters are checked.

�It is possible to write to the timer count variable from another PDD and disrupt the high-resolution timer.

�While TIMER0 is active (i.e., while it is taking interrupts), DOS sessions do not have access to timer 0.

�Performance tools such as C Set's DDE4XTRA.SYS and Visual Age's CPPOPA3. SYS are incompatible with this driver.

�Device drivers should not depend on having the first tick occur at any particular time.

If a driver registers for 1 millisecond, for example, the first tick might occur less than 1 millisecond after the registration.





=== Anomalies ===

The following anomalies currently exist in the use of the high-resolution timer:

�Having multiple device driver's attached to the high-resolution timer has not been tested.

�The high-resolution timer sets interrupts at 1 millisecond even if a slower rate would suffice. If one driver wants callbacks every 2 milliseconds and another wants them at 4 milliseconds, the driver could program IRQ 0 for 2-millisecond ticks, but it does not.

�HRT_FREE_POINTER does not currently do anything.

�While the high-resolution timer is taking interrupts, DOS sessions (VDMs) will not receive INT 8 or INT 1Ch calls. Only one device driver can receive interrupts on a given IRQ in OS/2; and VTIMER.SYS-the VDD that provides INT 8 and INT 1Ch services to VDMs-expects CLOCK0x.SYS to deliver IRQ 0 interrupts. Because the high-resolution timer gets IRQ 0 interrupts, CLOCK0x.SYS-and therefore VTIMER.SYS-cannot get them.





=== Real-Time MIDI Subsystem ===

The real-time MIDI subsystem (RTMIDI) provides real-time processing of MIDI data within the driver itself. The following sections describe how device drivers communicate with RTMIDI:

�[[00092.htm|IDC Interface]]<br />�[[00095.htm|Type-A Drivers]]<br />�[[00097.htm|Registering a Type-A Driver]]

Refer to the ''Multimedia Subsystem Programming Guide''(included with the IBM Developer's Toolkit for OS/2) for more information on the real-time MIDI subsystem.





=== IDC Interface ===

IDC stands for inter-device-driver communication. It is a technique for making function calls from one driver to another, thereby allowing the two drivers to communicate with one another. For more information on IDC, refer to the ''OS/2 Physical Device Driver Reference''.

Function prototypes and other declarations are found in MIDI_IDC.H. Note that &quot;function pointers&quot; and &quot;entry points&quot; are synonymous. All pointers, function or otherwise, are 16:16 (far) pointers.





=== Supported IDC Interfaces ===

The RTMIDI IDC interface is designed to support multiple &quot;types&quot; of client device drivers. An RTMIDI client device driver is a 16-bit physical device driver that registers itself with RTMIDI as a particular type. Currently, only Type A drivers are supported. The Type A drivers send and receive single MIDI bytes. This type is primarily intended for supporting the UART MIDI port on standard sound cards.

An individual physical device driver can be of multiple types and it can register itself with RTMIDI as many times as necessary. For instance, a sound card with four physical MIDI ports would make four Type-A registrations. RTMIDI would not realize that these four devices actually existed on one physical sound card and are handled by one driver.

The header file MIDI_IDC.H contains the function prototype for the entry points of RTMIDI. The initial call to the RTMIDI's main IDC entry point is used to obtain additional function entry points, one of each type.





=== Initializing IDC Communication ===

To initialize communication between your driver and RTMIDI:

Use the following code segment to obtain the main IDC entry point to RTMIDI and the entry points used to register the driver with RTMIDI. DevHelp_ AttachDD is used to obtain the main entry point, and DDTable.pfn retrieves the registration entry points.

This routine is normally executed when processing the init_complete strategy call. Make sure that DDTable is located in the current data segment (DS) and not on the stack (SS).



<pre class="western">MIDI_ATTACH_DD  DDTable;
MIDI_REGISTER  reg;

if (DevHelp_AttachDD(&quot;MIDI$ &quot;, (NPBYTE) &amp;DDTable ) )
{
  // Error
  // Return
}

reg.usSize=sizeof( MIDI_REGISTER );
DDTable.pfn(&amp;reg);</pre>




=== Type-A Drivers ===

Type-A drivers send and receive single bytes to and from RTMIDI. They are typically used for simple UART MIDI ports or simple synthesizers, such as those found on most sound cards.





=== Type-A Driver Capabilities ===

When Type-A drivers register with RTMIDI, they must provide information on their capabilities by setting the appropriate bits in the ''flCapabilities''field of the MIDIREG_TYPEA structure that is passed for registration. (See [[00097.htm|Registering a Type-A Driver]]for an example of registering a Type-A driver.) Flags marked with an asterisk (*) are not currently supported and should not be set. The flags are:

MIDICAPSA_INPUT Set this flag to indicate that this device can receive MIDI messages from RTMIDI. If set, then the pfnRecvByte and pfnRecvString fields in the MIDIREG_TYPEA structure must be properly initialized. If not set, then the corresponding hardware node cannot be enabled for receive.

MIDICAPSA_OUTPUT Set this flag to indicate that this device can send MIDI messages to RTMIDI. If not set, then the corresponding hardware node cannot be enabled for send.

MIDICAPSA_USES_BRIDGE * Set this flag to indicate that the device is a candidate for the MMPM/2 bridge.

MIDICAPSA_NOT_DEFAULT * Set this flag to indicate that this device should be selectable as the default device used by MIDISimpleOpen.

MIDICAPSA_RUNNING_STATUS Set this flag to tell RTMIDI that the device or the driver, or both, support running status.





=== Registering a Type-A Driver ===

The following is an example of registering a Type-A driver:

<pre class="western">USHORT __far __loadds __cdecl Open( USHORT  usPort, USHORT  usMode )
{
  // Open hardware
  // For example:  grab IRQ, send I/O commands to initialize the chips
}

USHORT __far __loadds __cdecl Close( USHORT  usPort, USHORT  usMode )
{
  // Close hardware
  // For example:  detach IRQ
}</pre>


<pre class="western">USHORT __far __loadds __cdecl RecvByte( USHORT  usPort, BYTE  b )
{
  // Send byte bData to hardware
  // For example:  via an outp() command
}

USHORT __far __loadds __cdecl RecvString( USHORT  usPort, BYTE __far *pb,
                                          USHORT  usLength )
{
  // Send byte bData to hardware
  // For example:  via an outp() command
}</pre>


<pre class="western">void __far __loadds __cdecl *Ioctl( PIOCTL_RP  pioc )
{
  // Process MMPM/2 IOCtl commands here, like volume change
  // pioc is a pointer to the actual IOCtl request packet
}</pre>


<pre class="western">HW_REGISTER  hwreg;
ULONG  ulHandle;
PFNSENDBYTE  pfnSendByte;

hwreg.usSize=sizeof( HW_REGISTER );
hwreg.in.flCapabilities = MIDICAPSA_INPUT | MIDICAPSA_OUTPUT;
hwreg.in.pszDeviceName=&quot;My Device&quot;;
hwreg.in.pfnOpen=Open;
hwreg.in.pfnClose=Close;
hwreg.in.pfnRecvByte=RecvByte;
hwreg.in.pfnRecvString=RecvString;</pre>


<pre class="western">if( !reg.pfnHWRegister( &amp;hwreg ) )
{
  // Error
  // Return
}

ulHandle=hwreg.out.ulHandle;
pfnSendByte=hwreg.out.pfnSendByte;</pre>






=== Audio Device Driver Exerciser (PMADDE) Tool ===

The Audio Device Driver Exerciser (PMADDE) is a PM-interface tool you can use to test code for low-level MMPM/2 components, such as audio device drivers or stream handlers. Using PMADDE, you can test various stages of your code at the Ring 0 level. This is useful when you want to verify that individual functions are working in your device driver without testing media control interface code (which might not be written yet). Each time you complete a function, you can test the function to see that it works, and then continue with the development of your driver.





=== Setting Up the Program ===

Before using PMADDE, OS/2 2.''x''with MMPM/2 must be installed on your computer. The PMADDE source files are located in the DDK\MMOS2\MMTOOLKT\ NEATSTUF\PMADDE subdirectory. To build the PMADDE program, change to the PMADDE subdirectory, type '''NMAKE''', and press Enter. Your output is the executable file (PMADDE.EXE). You can then type '''PMADDE'''from the command line to start the program. The Audio Device Driver Exerciser window is displayed. [Artwork not shown]

The PMADDE program defaults to the first waveform audio device it locates. To change the default option, select '''Options'''. Select '''Change Device'''to display the Change Audio Device window. [Artwork not shown]

This window contains information about each installed audio device including the logical device name, physical device name, and product information. Select the audio device you want to test.





=== PMADDE Functions ===

The PMADDE tool uses [[00111.htm|Stream Programming Interface Functions]]to test your audio device driver. The '''Data Stream'''menu on the Audio Device Driver Exerciser window includes the following choices: (See [[00108.htm|Stream Setup and Control]]for additional information on SPI functions.)

'''SpiGet Handler'''

This option sends an SpiGetHandler function to return a stream handler ID and ensure the stream handler is loaded. Although this function does not perform any actions on the audio device driver, you must complete this function before creating a stream.

'''SpiCreate'''

This option sends an SpiCreateStream function to the stream handler to create a data stream of a given data type. The data is then passed to the audio device driver using a [[00183.htm|DDCMD_REG_STREAM]]message, which establishes a communication link and registers a stream instance with the device driver.

'''SpiAssociate'''

This option sends an SpiAssociate function to link a [[00109.htm|stream object]]with a given stream source or target. A data object must be identified for use with a stream before the stream can be started.

'''SpiStart'''

This option sends an SpiStartStream function to start data streaming for a stream instance or group of streams. The device driver receives several calls including [[00190.htm|DDCMD_SETUP]], [[00204.htm|DDCMD_WRITE]], and [[00162.htm|DDCMD_CONTROL]](DDCMD_START) messages.

'''SpiStop'''

This option sends an SpiStopStream function to the stream handler, which is translated to the audio device driver as a [[00162.htm|DDCMD_CONTROL]](DDCMD_STOP) message.

'''SpiInstall Protocol'''

This option sends an SpiInstallProtocol function to install [[00110.htm|stream protocol]]in the stream handler. It also generates an internal Stream Protocol Control Block (SPCB) key, which is used to differentiate between multiple SPCBs of the same data stream type. If your device driver can perform using a type of data format that the MMPM/2 subsystem currently does not use as its default, use this option to install new protocol that your device driver supports.

'''SpiDestroy'''

This option sends an SpiDisableSync function to destroy the stream you created with '''SpiCreate'''. SpiDestroy calls the [[00162.htm|DDCMD_CONTROL]](DDCMD_STOP) and [[00169.htm|DDCMD_DEREG_STREAM]]messages at the inter-device driver communication (IDC) level. (See [[00052.htm|Inter-Device Driver Communication (IDC) Interface]].)

'''SpiSeek'''

This option sends an SpiSeekStream function to set the time within the audio device driver. You can seek the stream to a certain position, back to 0, or position it forward.

'''SpiQuery Time'''

This option sends an SpiGetTime function to the stream handler, which issues a [[00197.htm|DDCMD_STATUS]]message to the audio device driver to report the current stream time in milliseconds.





=== PMADDE Scenario ===

The following test scenario uses the PMADDE program to play back a waveform audio file from the source file system stream handler (FSSH) to the target audio system stream handler (AUDIOSH$). See [[00108.htm|Stream Setup and Control]]for detailed information on the phases of operation for a data stream.





=== Step 1 ===

To get a handler ID, select '''Data Stream'''. Select '''SpiGet Handler'''for a list of MMPM/2 installed handlers. [Artwork not shown]

Select AUDIOSH$ (audio stream handler) and FSSH (file system stream handler ), and select '''OK'''.

'''Note:'''AUDIOSH$ and FSSH are the only handlers that can be tested using the PMADDE program. The source code can be modified to create tools that test stream handlers other than AUDIOSH$ and FSSH.

The Active Handlers window then lists the handler names and classes and the IDs for AUDIOSH$ and FSSH. [Artwork not shown]

A handler ID is provided for an active handler to be a source (producer) and a target (consumer). After you have both a producer and consumer stream handler, you can advance to step 2 to create the stream.





=== Step 2 ===

To create the stream, select '''Data Stream'''. Select '''SpiCreate'''to display the Create Data Stream window. [Artwork not shown]

Enter the input source and target stream handler IDs. For example, enter the FSSH source ID (4) and the AUDIOSH$ target ID (2). Select a stream data type, and select '''OK'''.

The Stream State field in the Active Streams window displays information about the stream that has been created. The audio device driver has accepted the audio IOCtls and the IDC APIs to create the stream.





=== Step 3 ===

To associate the stream with an audio file, select '''Data Stream'''. Select '''SpiAssociate'''to display the Associate Data Stream window. [Artwork not shown]

Type the input stream number, an audio file name, and select '''OK'''. You can now start the stream you created, or you can create several streams.





=== Step 4 ===

To start the stream, select '''Data Stream'''. Select '''SpiStart'''to display the Start Stream window. [Artwork not shown]

Type the stream number and select a start flag. The SpiStartStream function starts data streaming in a specific stream or in a synchronized group of streams. Select the Start flag to start the stream immediately. Select the Preroll flag to cause the source stream handler to start and fill the buffers. An event is generated by the Sync/Stream Manager when a stream is prerolled. The application can then start the stream (or streams) for improved real-time response and initial synchronization of streams.

You can perform a stop at any time on the waveform audio file. To stop a stream, select '''Data Stream'''. Select '''SpiStop'''to display the Stop Stream window. [Artwork not shown]

Type the stream number and select the appropriate stop flag. There are three types of stops. The first is the regular stop or pause, which pauses the data stream but does not disturb any data. The second type of stop is a discard stop, which stops the stream immediately and discards any data left in the stream buffers. The third type is a flush stop, which stops the source stream handler, but the target stream handler continues until the last buffer held when the stop was requested is consumed by the target stream handler.

For a discard or flush stop, the Sync/Stream Manager detects when the stream handlers have stopped and return all buffers. At this point, the Sync/Stream Manager notifies the application with an EVENT_STREAM_STOPPED event in the Event Monitor window.

Streams can be restarted after a stop or end-of-stream (EOS). For the EOS case, the stream would need to be reassociated with another object or a seek backward to some point in the stream would need to be performed to actually start streaming again. A flush stop after a pause stop causes the stream to flush the existing buffers to the output device.

'''Note:'''Typically, data streaming continues until the end of the stream. When this happens, the Sync/Stream Manager sends an EVENT_EOS event to the event routine of the application. To restart the stream after you have paused or stopped it, select '''SpiStart'''from the '''Data Stream'''menu. The program restarts the stream and informs you when an end-of-stream (EOS) is reached.





=== Step 5 ===

To get the stream time, select '''SpiQuery Time'''from the '''Data Stream'''menu. [Artwork not shown]

Type the input stream number and select '''OK'''. The stream time is displayed in milliseconds.





=== PMADDE Script Interface ===

To pipe a test script that already exists into the program, select '''Run Script File'''from the '''Options'''menu. [Artwork not shown]

Select the script file you want to pipe into the PMADDE program, and select '''OK'''. If the script file exists, the user interface of the PMADDE program is disabled and commands are accepted from the script file only. The following figure is an example of a PMADDE test script.

<pre class="western">;*****************************************************
;**  Audio Device Driver Exerciser V 1.0
;**    Test Script File.
;*****************************************************
BEGIN                 ;
DEVICENAME AUDIO1$    ; device name
GETHANDLER  AUDIOSH$  ; stream handler name
GETHANDLER  FSSH      ;
CREATE  3  2  3       ; Source ID, Target ID &amp; Data type index
SLEEP 1000            ; Sleep for 1000 milliseconds
CREATE  3  2  3       ;
SLEEP 1000            ;
ASSOCIATE  1  WELCOM.WAV  ; stream number &amp; Audio file
SLEEP 1000            ;
ASSOCIATE  2  PMADDE.WAV  ;
SLEEP 1000            ;
START  1  0           ; stream number &amp; flag (0=Start, 1=Preroll)
SLEEP 5000            ;
START  2  0           ;
END                   ;</pre>
The following information describes the syntax associated with the PMADDE script language.

'''Syntax Description'''

BEGIN Starts the script file.

DEVICENAME ''device name''Specifies the physical ''device name''.

CREATE ''hidSource hidTarget datatype''Creates a data stream of ''datatype''from ''hidSource''to ''hidTarget''. Select '''SpiCreate'''from the '''Data Stream'''menu to view the stream data types available. The data types listed correspond to a number beginning with 0. The second data type in the list is 1, the third is 2, and so on. To create a data stream from FSSH to AUDIOSH$ of data type PCM, 16-bit, 44 kHz, and mono, type the following:

<pre class="western">CREATE 4 2 3;</pre>
ASSOCIATE ''stream # filename''Associates a data stream with a data object.

START ''stream# startflags''Starts a data stream. The ''startflags''can be one of the following:

�PREROLL <br />�START

STOP ''stream# stopflags''Stops a data stream. The ''stopflags''can be one of the following:

�FLUSH <br />�DISCARD <br />�PAUSE

SEEK ''stream# mode units position''Seeks to the specified ''position''in the data stream using the specified ''units''and specified ''mode''.

DESTROY ''stream#''Destroys the specified stream.

QRYTIME ''stream#''Queries the stream time of the specified stream.

SLEEP ''sleepinterval''Suspends execution of the script file for the duration of the

END Ends the script file.

You can also create a test script by recording your keystrokes to be piped into the PMADDE program at a later time. You must specify a name for the script file you want to create when starting the PMADDE program. If the script file exists, the user interface is disabled and commands are accepted from the script file only. If the script file specified does not already exist, all actions are recorded and a script file is created. For example, to create a script file named TEST.SCR, use the following syntax:

<pre class="western">PMADDE TEST.SCR logfile</pre>
'''Note:'''You must specify a ''logfile''(for example, TEST.LOG) when creating a test script. If you are using the command-line interface to execute a test script that already exists, you must also specify a ''logfile''.





=== Stream Setup and Control ===

There are five phases of operation for a data stream:

1.Configuration <br />2.Creation <br />3.Association <br />4.Streaming/Synchronization <br />5.Destruction

Each of these five phases involves specific operational steps that an application can control. In any phase, the program can take action to modify certain options. The five phases are described below.

Phase 1. Configuration

After installation, each system has predefined or default connection configurations that allow applications to operate according to general default parameters chosen by the user or by the installation program. An example of stream configuration is where waveform audio data is configured to stream to the Line 1 Output on the IBM Audio Playback and Capture Adapter. This is a default connection that determines which hardware output resource the waveform audio stream will connect to. These configuration options are established when you run the Multimedia Setup program of the MMPM/2 system. Application installation utility programs can also set up connection defaults. Note that the source and target stream handler, as well as the source and target device association, must be specified when the stream is created.

<pre class="western"> [Artwork not shown] </pre>
Phase 2. Creation

When a media control driver (or other multimedia application) determines that data will be streamed between devices, it can invoke SpiCreateStream, which results in the stream being created. The caller specifies the source and target stream handler IDs, source and target device-specific information, and the stream data type. (Use the SpiEnumerateHandlers function to return a list of stream handler names. You can then use the SpiGetHandler function to return a handler ID given a handler name. Use the SpiEnumerateProtocols function to determine which data types a given stream handler can process.)

<pre class="western"> [Artwork not shown] </pre>
The Sync/Stream Manager notifies each of the two stream handlers that a stream is being created, and each stream handler must return a valid stream protocol control block (SPCB) to the Sync/Stream Manager. The Sync/Stream Manager will negotiate the parameters of the stream and notify the handlers by a SHC_NEGOTIATE_RESULT call to each handler. Negotiation consists of determining which SPCB parameters both stream handlers can accept. This includes stream buffer sizes and the number of buffers needed to maintain continuous streaming of data.

Typically, the Sync/Stream Manager allocates buffers for the stream, but it is possible to use the application buffer directly. The SPCBBUF_ USERPROVIDED flag in the SPCB indicates whether to use provided buffers or to allocate buffers. This is useful for streaming to or from the memory stream handler. In a split stream situation, a particular stream might not allocate its own buffers but use the buffers of another stream. In other words, it might share buffers. This is useful for interleaved data coming from one source but going to more than one destination.

For Sync/Stream Manager-allocated buffers, stream buffer allocation is done during stream creation. The number of buffers to allocate is taken from the &quot;negotiated&quot; SPCB. The buffers are allocated and then locked, so that they will not be paged out to disk. The buffers are unlocked and freed upon an SpiDestroyStream request. These buffers are available at Ring 3 in the process linear space and Ring 0 in global linear system memory. The Sync/Stream Manager will provide global descriptor table (GDT) selectors to allow Ring 0 stream handlers to access the buffer memory. The stream handler can assume that the Sync/Stream Manager manages the GDT selectors used. The maximum buffer size is 64KB.

Both handlers (source and target) share access to the buffers allocated by the Sync/Stream Manager. Note that if the minimum buffer space (specified in the SPCB) is not available, the stream creation will fail. The allocation of memory when the stream is created prevents the need to perform allocations of physical memory when the stream is active, which could result in disruption of data flow affecting the real-time performance of the stream. Therefore, it is advantageous to allow the Sync/Stream Manager to allocate buffers and lock them at stream creation time instead of providing buffers to the Sync/Stream Manager that probably cannot be locked when the stream is created.

Phase 3. Association

After a stream is created, and before it is possible to start the stream, it is necessary to make sure that a data resource, or ''stream object'', is identified for use with the stream. For example, if the application wishes to stream waveform data from application memory (the application dynamically creates the waveform), then the application must make an association between the stream and the memory object. This is accomplished using the SpiAssociate function.

<pre class="western"> [Artwork not shown] </pre>
An association for a specific stream handler must match the type of the stream handler as well as the data type of the stream. Each stream handler will list supported object types in response to calling SpiEnumerateProtocols. Note that only one data object can be associated with a stream once the stream is created, and it is specific to a particular stream handler (that is, source or target). Associations can be changed, but the stream cannot be active; it must be stopped first (discard stop, flush stop, or EOS). The SpiAssociate function can be used to &quot; reassociate&quot; data objects for a stream handler as long as the stream handler is the type that the stream was created to handle.

'''Note:'''Devices should be associated with stream handlers only when the stream is created.

Phase 4. Streaming/Synchronization

There are several stream operation functions, and each can be used in conjunction with stream synchronization.

<pre class="western"> [Artwork not shown] </pre>
The following paragraphs contain outlines of the function descriptions.

SpiStartStream Starts data streaming in a specific stream or a synchronized group of streams, depending on the flags for this function. This function also allows a stream or group of streams to be prerolled. Preroll allows the source stream handlers to start and fill the buffers. An event is generated by the Sync/Stream Manager when the streams are prerolled. The application can then start the streams for better real-time response and initial synchronization of streams.

If multiple streams are involved, when the synchronization master is started or prerolled, all ''slave''streams can also be started or prerolled. This synchronization relationship can be set up by using the SpiEnableSync function after all streams are created.

The active stream protocol governs the amount of data buffered and the rate of data flow maintained. Both source and target stream handlers are controlled by the stream protocol (SPCB). Both handlers contribute to the contents of the SPCB when the stream is created. Stream events such as cue points are detected by the appropriate stream handler and an event notification is sent to the process that owns the stream.

SpiStopStream Stops data streaming in a given stream or streams. There are three types of stops for this command. The first is the regular stop or pause, which pauses the data stream, but does not disturb any data. The second kind of stop is a discard stop, which requests that the stream be stopped immediately and the data left in the stream buffers be discarded. The third type is a flush stop. This stop requests that the source stream handler be stopped, but that the target stream handler continue until the last buffer held at the time the stop was requested is consumed by the target stream handler.

For a discard or flush stop, the Sync/Stream Manager will detect when the stream handlers have stopped and return all buffers. At this point, the Sync/Stream Manager notifies the application with an EVENT_STREAM_STOPPED event.

Streams can be restarted after a stop or end-of-stream (EOS). For the EOS case, the stream would need to be reassociated with another object or a seek backward to some point in the stream would need to be performed to actually start streaming again. A flush stop after a pause stop causes the stream to flush the existing buffers to the output device.

'''Note:'''Typically, data streaming continues until the end of the stream. When this happens, the Sync/Stream Manager sends an EVENT_EOS event to the applications event routine.

SpiSeekStream Seeks to a specific point in the stream source object. Depending on the type of object associated with the stream at a source or target, this function directs the appropriate stream handler to relocate the ''current stream index'', or position, to the specified location. The object types that support this function are memory, file, CD track, and library object. Use this function to reposition the stream forward or backward from its current position. This can be performed only on a newly created, unstarted stream or a stopped stream (discard stop, flush stop, or EOS).

SpiEnableSync Establishes stream synchronization between multiple streams. Stream synchronization is automatically handled by the stream protocol, depending on whether a given stream is the synchronization ''master''or ''slave''. Once a synchronization relationship is established, synchronization is maintained according to real-time events detected at the master and passed on to the slaves. The application does not have additional stream events to process due to synchronization. Only one stream can be a master.

SpiDisableSync Stops stream synchronization for a given stream or streams. A previously designated stream master is disabled, and all synchronization under that master is deactivated.

SpiGetTime Fills in the current stream-specific time information. This allows an application to query the stream time. This function is supported for any stream that is active or stopped, and will not disrupt data transport in the stream. A more accurate method to determine the stream time is to enable stream time events, which will report stream time continuously and in real-time to the application.

Phase 5. Destruction

When a stream is no longer to be used by an application, it must be destroyed. Note that the stream handlers involved can remain active with other streams, and will remain available to create additional streams ( without additional calls to SpiGetHandler). The application will receive no further stream events in its event handling routine after calling the SpiDestroyStream function. All system resources allocated to the stream are released, including the physical memory used to create stream buffers. After the stream is destroyed, the stream handler state reverts back to its condition immediately prior to the creation of the stream. If the stream being destroyed is a master stream of a sync group, all synchronization under that master stream will become inactive. If the stream is a slave in a sync group, the stream will be removed from the sync group and will not affect the master or other slave streams in the group.





=== stream object ===

A stream object is the data resource or device channel that represents either the data source or target for a stream. In order for a stream to obtain data, it must be associated with a ''source stream object''. This can be a waveform audio data object such as a file on the file system, or it can be a MIDI mapper stream handler from the MIDI hardware adapter. Also, the stream target handler must be associated with a ''target stream object''. This could be a file which will be written to, or it could be an output device that will store, convert, or transmit the data.

Association of a stream with a source stream object, target stream object, or both may be permanent. In other cases, associations must be made whenever the stream is created and before the stream may be manipulated. For example, if there is only one audio adapter with only one input line, then the audio stream handler device driver will always associate a stream with that input line whenever it acts as a source.

Associations are tied to the concept of connections at the media control interface level of the system. Default connections can be made between logical devices and the actual physical device that performs the function of the logical device. Media drivers must use this connection information to determine the source and target handler names to be used on a subsequent SpiGetHandler. The connection information is also used to provide the source and target device or object associations used on an SpiCreateStream function.

Devices may be associated with stream handlers at stream creation time only . An SpiAssociate request can be used, however, to &quot;re-associate&quot; data objects with stream handlers after the stream has been created. The stream must be stopped (discarded, flushed, or EOS) to do this.





=== stream protocol ===

A stream protocol defines key parameters that control the behavior of a data stream. The application can query, install, or deinstall a specific SPCB from a stream handler. Each stream handler supports one or more stream protocols. An SPCB is uniquely identified by the value of the stream data type (SPCB key). One field in the SPCB key allows the stream handler to have multiple SPCB's installed for the same data type. This field can be used by an application to specify which SPCB, for any data type, it wants to use. Each application in the system could define multiple SPCB for the same data type (see the ''ulType''field in the SPCBKEY data structure). The application can modify a stream protocol by installing a new SPCB and deinstalling the old SPCB.





=== Stream Programming Interface Functions ===

The stream programming interface (SPI) contains functions exported by the Sync/Stream Manager to support applications that control real-time data streams. These functions are used to perform stream creation, association, configuration, operation, synchronization, and destruction functions. SPI functions also include enabling applications to modify Stream Protocol Control Blocks (SPCBs) and querying a stream's time information.

<pre class="western">/-------------------------------------------------------------\
|Function                  |Description                       |
|--------------------------+----------------------------------|
|SpiAssociate              |Associates a data object with a   |
|                          |stream handler.                   |
|--------------------------+----------------------------------|
|SpiCreateStream           |Creates a stream instance between |
|                          |a source and a target stream      |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiDestroyStream          |Removes a stream instance from the|
|                          |system.                           |
|--------------------------+----------------------------------|
|SpiDetermineSyncMaster    |Determines the best master stream |
|                          |to be used in a sync group.       |
|--------------------------+----------------------------------|
|SpiDisableEvent           |Disables event detection for a    |
|                          |particular event.                 |
|--------------------------+----------------------------------|
|SpiDisableSync            |Removes a group of streams.       |
|--------------------------+----------------------------------|
|SpiEnableEvent            |Enables event detection for a     |
|                          |particular event.                 |
|--------------------------+----------------------------------|
|SpiEnableSync             |Establishes a group of streams to |
|                          |synchronize the streams.          |
|--------------------------+----------------------------------|
|SpiEnumerateHandlers      |Returns a list of the stream      |
|                          |handler names installed in the    |
|                          |SPI.INI file.                     |
|--------------------------+----------------------------------|
|SpiEnumerateProtocols     |Returns a list of stream protocol |
|                          |keys for the specified stream     |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiGetHandler             |Returns the handler ID for the    |
|                          |specified stream handler.         |
|--------------------------+----------------------------------|
|SpiGetProtocol            |Queries a stream handler for a    |
|                          |specified stream protocol.        |
|--------------------------+----------------------------------|
|SpiGetTime                |Queries the current stream time.  |
|--------------------------+----------------------------------|
|SpiInstallProtocol        |Installs or removes a specified   |
|                          |stream protocol for a stream      |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiSeekStream             |Seeks to a specified point in the |
|                          |stream object or sets the current |
|                          |stream time.                      |
|--------------------------+----------------------------------|
|SpiStartStream            |Starts data streaming for a single|
|                          |stream instance or a group of     |
|                          |streams.                          |
|--------------------------+----------------------------------|
|SpiSendMsg                |Sends a message to a stream       |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiStopStream             |Stops data streaming for a single |
|                          |stream instance or a group of     |
|                          |streams.                          |
\-------------------------------------------------------------/</pre>




=== AP2/P2STRING Tool ===

This chapter describes the AP2 and P2STRING tools.





=== AP2 ===

AP2 is the easiest and most complete automated method of testing the audio and video device driver. AP2 provides an easy to use PM interface to the P2STRING tool with a complete set of test scripts for the audio and video device driver. AP2 queries the device driver to determine the functions it supports by using the capability MCI (media control interface) string command. Based on these compatibilities, AP2 will create a list of test scripts that are supported by the default device drivers. You can run any combination of these scripts.

The AP2 tool consists of the file AP2.EXE, AP2.HLP, and AP2.INI and P2S_ DESC.TXT. AP2 also requires the P2STRING tool consisting of P2STRING.EXE AND P2S_DLL.DLL. These files are located in the ''IBM Developer Connection Device Driver Kit for OS/2''. The AP2 script files are located in a subdirectory under AP2 called SCRIPTS, and the data files are located in another subdirectory called DATA.

AP2 does not require any parameters If AP2 is entered from the command line , AP2 will run, test the device capabilities and display all scripts that can be tested. The file P2S_DESC.TXT file contains the descriptions for all the AP2 test scripts. The results of the capability test are placed in the file CAPABLTY.TXT.

The following table shows the parameters that are available for AP2. The AP2 parameters include:

<pre class="western">/-------------------------------------------------------------\
|Parameter                |Description                        |
|-------------------------+-----------------------------------|
|[script_file]            |Specifies the script files to be   |
|                         |used. The default is *.P2S.        |
|                         |Wildcards *,? are supported.       |
|-------------------------+-----------------------------------|
|[-AMPMIX]                |Specifies that the Ampmix scripts  |
|                         |will be selected when AP2 is       |
|                         |started. Ampmix scripts are denoted|
|                         |by an 'A' in the first character in|
|                         |the filename.                      |
|-------------------------+-----------------------------------|
|[-CD]                    |Specifies that the CD scripts will |
|                         |be selected when AP2 is started. CD|
|                         |scripts are denoted by a 'C' in the|
|                         |first character in the filename.   |
|-------------------------+-----------------------------------|
|[-CDXA]                  |Specifies that the CDXA scripts    |
|                         |will be selected when AP2 is       |
|                         |started. CDXA scripts are denoted  |
|                         |by an 'X' in the first character in|
|                         |the filename.                      |
|-------------------------+-----------------------------------|
|[-MIDI]                  |Specifies that the MIDI scripts    |
|                         |will be selected when AP2 is       |
|                         |started. MIDI scripts are denoted  |
|                         |by an 'M' in the first character in|
|                         |the filename.                      |
|-------------------------+-----------------------------------|
|[-WAVE]                  |Specifies that the Wave scripts    |
|                         |will be selected when AP2 is       |
|                         |started. Wave scripts are denoted  |
|                         |by a 'W' in the first character in |
|                         |the filename.                      |
|-------------------------+-----------------------------------|
|[-VIDEO]                 |Specifies that the Video scripts   |
|                         |will be selected when AP2 is       |
|                         |started. Video scripts are denoted |
|                         |by a 'V' in the first character in |
|                         |the filename.                      |
|-------------------------+-----------------------------------|
|[-MPEG]                  |Specifies that the MPEG scripts    |
|                         |will be selected when AP2 is       |
|                         |started. MPEG scripts are denoted  |
|                         |by &quot;_M&quot; as the first two characters|
|                         |in the filename.                   |
|-------------------------+-----------------------------------|
|[-INTERACTIVE]           |Specifies that the Interactive     |
|                         |scripts will be selected when AP2  |
|                         |is started. An interactive script  |
|                         |requires some form of user input   |
|                         |during the execution of the script.|
|                         |A script is denoted as interactive |
|                         |by an 'I' in the seventh character |
|                         |in the filename.                   |
|-------------------------+-----------------------------------|
|[-ALL]                   |Specifies that all loaded scripts  |
|                         |will be selected.                  |
|-------------------------+-----------------------------------|
|[-BATCH]                 |Specifies that testing will be in a|
|                         |batch mode. One or more of the     |
|                         |above selection parameters is      |
|                         |required to specify which scripts  |
|                         |are to be tested. In batch mode AP2|
|                         |will automatically start testing,  |
|                         |log any messages to an output file |
|                         |and terminate when complete. If the|
|                         |interactive switch is used in      |
|                         |conjunction with batch, interactive|
|                         |will be ignored, and no interactive|
|                         |scripts are tested in batch mode.  |
|                         |All output and failed scripts are  |
|                         |logged to an output file. If an    |
|                         |output file is not specified, the  |
|                         |default is AP2.OUT.                |
|-------------------------+-----------------------------------|
|[-oOUT_FILE]             |If this parameter is specified, all|
|                         |scripts that FAIL will also be     |
|                         |logged to this file.               |
|-------------------------+-----------------------------------|
|[-TEST]                  |Specifies that AP2 will            |
|                         |automatically test device          |
|                         |capabilities at startup.           |
|-------------------------+-----------------------------------|
|[-NOTEST]                |Specifies that AP2 will preform no |
|                         |testing of device capabilities at  |
|                         |startup.                           |
|-------------------------+-----------------------------------|
|[-DATAPATH]              |Specifies the data path to be used |
|                         |by AP2. This is the same as        |
|                         |selecting the Data Path button.    |
\-------------------------------------------------------------/</pre>




=== Starting and Running AP2 ===

When running AP2 for the first time, it is necessary to set the Data Path. The Data Path points to the directory where all the data files for AP2 are located. Every AP2 script that requires a data file uses an environment variable AP2PATH, which is set by AP2.
 [Artwork not shown]
The '''Start Test'''button tests the selected scripts. To test scripts, highlight the selected scripts and click on the '''Start Test'''button. After each script is completed, the status for that script is displayed. The output for every script is located in the OUT directory. The output file has the same name as the script with the extension of &quot;OUT&quot;.

The '''View Output''' button allows the viewing of the files that are generated from the execution of the *.P2S files. To view the output for a specific script, highlight the script, and click on the '''View Output'''button.

The '''Data Path''' button displays a dialog box and allows you to select the location of the AP2 data directory. AP2 will not run correctly if the data path is not set to the directory containing the AP2 data files.





=== P2STRING ===

Use the P2STRING script processing tool to test media control interface string commands in the MMPM/2 environment.

The P2STRING tool processes script files (containing string commands and tool directives) to test string commands in your application programs. The P2STRING tool tests your low-level components at the Ring 3 level (as compared to the PMADDE tool, which tests code at the Ring 0 level). P2STRING extracts the strings from the script files and processes the commands through the mciSendString function. Messages and error conditions of the processes included in the scripts are logged to an output file and displayed in windows. P2STRING comes with a set of predefined scripts to test audio and video functions. These tests are a group of test files called ''test suites''. For more information about test suites, see [[00127.htm|Testing Device Drivers]].

Each process logs to its own display window, but all processes log to the same output file. In addition, if you close the display window, the string execution thread is immediately destroyed and the entire process ends.

<pre class="western"> [Artwork not shown] </pre>
Output messages include all non-comment lines read from the script (for example, script directives, command strings, expected return values, expected and received notify messages, and status lines). In addition, errors and debugging statements of unsuccessful string commands are logged to a file named P2STRING.LOG file.





=== Setting Font Size and Type ===

Before you start the P2STRING tool, you can change the size and type of font displayed in the P2STRING window on the desktop. For example, to specify Times Roman font with a 10 point font size, type:

<pre class="western">SET P2STRING_FONTFACE=TIMES
SET P2STRING_FONTSIZE=10</pre>
You can specify either font face, font size, or both. Possible FONTFACE values include SYSTEM, COURIER, TIMES, or HELVETICA (default). Possible FONTSIZE values include 8 (default), 10, 12, 14, or 18.





=== Starting P2STRING ===

The P2STRING tool consists of two files: P2STRING.EXE and P2S_DLL.DLL. These files are located in the ''IBM Developer Connection Device Driver Kit for OS/2''. The following example displays the syntax used to start the P2STRING program. Associated parameters are described in the following table.

<pre class="western">P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]</pre>
'''Note:'''The parameters are case sensitive.

The following list describes the parameters associated with the P2STRING program.

'''Parameter Description'''

''script_file''Specifies the script file name you want to process.

'''Note:'''Refer to [[00118.htm|P2STRING Script Language]]for information on the contents of a script file and how to interpret the script language.

[-a]''out_file''Specifies the output file name containing the results of the test. This file contains only the results of the test you are running, unless you specify the optional -a parameter. For example, to append the output of a script file named SAMPLE.SCR to output currently in a file named MDM.OUT, type:

<pre class="western">P2STRING SAMPLE.SCR -aMDM.OUT</pre>
[-e''err_file''] Specifies the optional error file name that receives messages from string commands that completed unsuccessfully. For example, to create an error file named MDM.ERR, type:

<pre class="western">P2STRING SAMPLE.SCR MDM.OUT -eMDM.ERR</pre>
[-d|-D] Specifies one of the following optional parameters:

<pre class="western">-d     Instructs P2STRING to end after processing a script file.
       Use this parameter when you are running test cases automatically  .
       There is no change in the output.
       When the script file has completed processing, P2STRING prompts 
       you with a message requiring you to end the test.
-D     Behaves identically to the -d parameter except that the script 
       directives requiring user input are ignored.</pre>
'''Note:'''Refer to [[00120.htm|Tool Directives]]for information on how to add execution directives (which require user input) in a script file.

-E Causes the script file to exit after the first error. By default, script files run to completion regardless of errors. For example, the following command ends the processing of SAMPLE.SCR after an error is encountered:

<pre class="western">P2STRING SAMPLE.SCR -aMDM.OUT -d -eMDM.ERR -E</pre>
-t Records time stamps for strings and MM_MCIPASSDEVICE notification messages.





=== P2STRING Script Language ===

This section describes the contents of a script file and how to interpret the script language. Script files can contain several types of lines including:

�[[00119.htm|Comments]]<br />�[[00120.htm|Tool Directives]]<br />�[[00121.htm|MMPM/2 String Commands]]<br />�[[00122.htm|Expected Return Strings]]<br />�[[00123.htm|Expected Error Messages]]<br />�[[00124.htm|Expected Notification Messages]]

The following example displays an example of how a script file appears.

<pre class="western">@ PROCESSES = 2 
@ EVENTS = { HASCTRL1 = 1 , HASCTRL2 = 0 } 
# 
# 
# 
@ PROCESS   1 
; 
;   set   masteraudio   level   for   session   to   10 %   -   will   affect   all 
;   3   processes 
; 
masteraudio   volume   10 
; 
;   open   waveaudio   device   non - exclusively 
; 
open   waveaudio   alias   wav1   shareable   notify 
+ MM _ MCINOTIFY   MCI _ NOTIFY _ SUCCESSFUL   MCI _ OPEN   # 1 
@ WAIT _ NOTIFY   1   60000 
@ WAIT _ PASSDEVICE   wav1   60000 
@ WAIT _ NOTIFY   21   60000 </pre>




=== Comments ===

Script comment lines must start with either a ''semi-colon''(;) or ''comment sign''(#) in the first column. These comment lines are neither displayed nor echoed in the output file. If you want a remark to appear in the output, use the @REM directive.

P2STRING allows for a variable number of lines to be displayed in its window. Regular comment lines (header lines) are not displayed nor written to the output file.





=== Tool Directives ===

The P2STRING tool supports either multithreaded or multiprocess execution, but not both. You can use tool directives to test either @PROCESSES or @ THREADS in a script file.

Tool directives start with an ''at sign''(@) in the first column. These directives affect the execution and appearance of the output. The following classes of directives are recognized:

�Initialization <br />�Execution

Initialization Directives

Use initialization directives to set up the content of the script file. These directives must appear before execution directives because the tool preprocesses the script file and builds process command buffers.

The @THREADS and @PROCESSES directives are mutually exclusive. In other words, the P2STRING tool supports either multithreaded or multiprocess execution in a script file (not both). In addition, there is a limit of 10 processes or threads per script file.

The following table lists the supported initialization directives.

'''Directive Description'''



<pre class="western">@PROCESSES=x</pre>
Specifies the number (''x'') of processes the script file will be running. For example:

<pre class="western">@PROCESSES=2</pre>


<pre class="western">@THREADS=x</pre>
Specifies the number (''x'') of threads the script file will be running.



<pre class="western">@EVENTS={n[=0|1] [,n[=0|1]]}</pre>
Specifies one or more ''n''ames of events. Events are user-defined with a maximum of 15 characters. Events can be set to 1 or 0. Set an event to 1 for an event that is set with the @SET_EVENT execution directive. Set an event to 0 to clear or reset the event. If no initialization values are specified, the event is initialized to 0. For example:

<pre class="western">@EVENTS={brad=1,john=1,test=0}</pre>


Execution Directives

Use execution directives to process the script file. Again, the @THREAD and @PROCESS directives are mutually exclusive.

The following table lists the supported execution directives.

'''Note:'''Timing out on the @WAIT_EVENT and @WAIT_NOTIFY directives is ''not''considered a failure.

'''Directive Description'''



<pre class="western">@THREAD x</pre>
Specifies that the script lines following this directive belong to thread number ''x''until the next @THREAD directive is encountered.



<pre class="western">@PROCESS x</pre>
Specifies that the script lines following this directive belong to process number ''x''until the next @PROCESS directive is encountered.



<pre class="western">@SET_EVENT name 0|1</pre>
Sets the event ''name''to either 1 or 0. Use 1 to mark that the event has happened. Use 0 to clear or reset the event.

'''Note:'''The event must be declared through the @EVENTS directive.



<pre class="western">@WAIT_EVENT name [to]</pre>
Waits until the event ''name''is set to 1. @WAIT_EVENT does not cause a change of the event state. If you need a reusable event, use this directive.

The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.



<pre class="western">@WAIT_NOTIFY x [to]</pre>
Waits for a specific number (''x'') from an expected MM_ MCINOTIFY notification message. This number must match the index used in the MM_MCINOTIFY reference line. The @WAIT_NOTIFY events are not reusable because there are no events that logically reset it.

The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.

If the associated mciSendString function fails, the event is posted to prevent delays for notifications that are never going to be sent.



<pre class="western">@WAIT_PASSDEVICE alias [to]</pre>
Waits until the device instance with an alias of ''alias''gains use. This assumes that the alias names used within a script file are unique. The maximum alias name length is 20 characters.

'''Note:'''Use a unique alias for every OPEN command.

The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.

The tool assumes that a unique alias is specified on each OPEN string command. If unique aliases are not used, errors conditions might occur.



<pre class="western">@REM comment</pre>
Echoes the ''comment''to the screen and the output log file. All other script comment lines (those starting with ''';'''or '''#''') are neither transferred nor displayed.



<pre class="western">@PAUSE to</pre>
Pauses processing of the current thread or process in the input script file for the specified time. It does not stop the processing of the notifications or window functions. Other threads or processes are not affected by this directive.



<pre class="western">@BREAK   [ message ] </pre>
Causes a message box to appear with ''message''text. Script processing is halted until the user responds with the correct action . For example:

<pre class="western">@BREAK [replace the CD]</pre>


<pre class="western">@CHECK [message]</pre>
Grades the success of the previous command based on the user's response. A pop-up window displays the ''message''and prompts the user with Yes or No push buttons. The status is passed if the user selects Yes, or failed if No is selected. For example:

<pre class="western">@BREAK The music will play for 5 seconds.  Ready to time it?
play cdaudio notify
@PAUSE 5000
@CHECK Did it play?</pre>






=== MMPM/2 String Commands ===

All lines that do not fall into any of the other categories are interpreted as MMPM/2 string commands. These lines are passed to the Media Device Manager (MDM) through the mciSendString function after the environment variables have been substituted.

Any token in the string command line bracketed by question marks (such as ? FOO?) is interpreted as an environment variable. The actual value of the environment variable is substituted into the string before it is passed to the mciSendString function. If the variable is not found, a warning is issued and the token is replaced with a null string. For example, assuming the environment string MMDATA is set to D:\DATA, open ?mmdata?\temp.wav alias a is equal to open d:\data\temp.wav alias a.





=== Expected Return Strings ===

Many MMPM/2 commands return strings. It is possible to check these strings against an expected value with an expected return string line.

An expected return string line has the format:

<pre class="western">=result</pre>
The ''equal sign''(=) must be in column 1 and should have no trailing spaces. If an empty string is expected, nothing should follow the = (not even spaces). For example:

<pre class="western">status cdaudio ready wait
=TRUE
status cdaudio mode wait
=stopped</pre>
The expected result is always interpreted as a string. This might produce some unusual outputs for commands that return binary data.

Where the return is a textual numerical value, it can be matched to a tolerance range of +/-10% using a ''tilde''(~) before the number. This is typically used when the exact value cannot be known. For example:

<pre class="western">set foo time format milliseconds wait
play foo notify
@PAUSE 1000
stop foo wait
status foo position wait
=~1000</pre>
Thus, the status command is considered successful if the returned string is in the range 900 - 1100.





=== Expected Error Messages ===

When an MMPM/2 string command is expected to fail with an error, use the expected error line to specify the expected error. The expected error line has the format:

<pre class="western">=!error</pre>
The =! must start in column 1. If any error is acceptable, then use the keyword ERROR. If a specific error is expected, type the exact error message after the =!. For example:

<pre class="western">open sequencer alias mymidi wait
load mymidi nofile.foo
=!File not found.</pre>
Be careful about extra blanks in the expected-error and expected-result lines. The case of the strings is unimportant; however, the comparison will fail if the spacing or punctuation does not match exactly.





=== Expected Notification Messages ===

Many MMPM/2 string commands cause notification messages to be sent to the P2STRING tool. The system uses notification messages to respond to applications. For example, notification messages indicate system status regarding completion of a media device function or passing of the ownership of a media control device from one process to another.

It is possible to verify that the proper notifications are received by using an expected-notify line. Each expected notification line begins with a ''plus sign''(+) in column 1. The following types of notification lines are possible:

�Command completion/error notifications <br />�Event notifications <br />�Position change notifications

'''Note:'''Any or all notification messages might be expected for a single MMPM /2 string command.

Command Completion/Error Notifications

A MM_MCINOTIFY line notifies an application when a device successfully completes the action indicated by a media message or when an error occurs.

<pre class="western">+MM_MCINOTIFY  notify-code [#x]</pre>


<pre class="western">/-------------------------------------------------------------\
|Keyword           |Description                               |
|------------------+------------------------------------------|
|notify-code       |Specifies the notification message code,  |
|                  |for example, MCI_NOTIFY_SUCCESSFUL. The   |
|                  |spelling must be the same as the #defines |
|                  |in the OS2ME.H file for the notify codes. |
|------------------+------------------------------------------|
|message           |Specifies the media control interface     |
|                  |message that caused the notification, for |
|                  |example, MCI_PLAY. The spelling must be   |
|                  |the same as the #defines in the OS2ME.H   |
|                  |file for media control interface messages.|
|------------------+------------------------------------------|
|x                 |Specifies a unique number (x) used to     |
|                  |associate @WAIT_NOTIFY directives with    |
|                  |particular notifications. This number has |
|                  |nothing to do with the order in which     |
|                  |strings are sent. The number must be      |
|                  |unique and in the range 1-99.             |
\-------------------------------------------------------------/</pre>
Event Notifications

A MM_MCIPOSITIONCHANGE line notifies an application of the current media position.

<pre class="western">+MM_MCIPOSITIONCHANGE position %user-parameter #x</pre>


<pre class="western">/-------------------------------------------------------------\
|Keyword           |Description                               |
|------------------+------------------------------------------|
|position          |Specifies the expected MMTIME position of |
|                  |the first position-change message.        |
|------------------+------------------------------------------|
|user-parameter    |Specifies the user parameter to be        |
|                  |returned. This should be the same as the  |
|                  |return value specified in the             |
|                  |SETPOSITIONADVISE string command. Note    |
|                  |that the return value must be a unique    |
|                  |integer in the range of 1 - 99.           |
|------------------+------------------------------------------|
|x                 |Specifies the number (x) of position      |
|                  |change messages expected. For further     |
|                  |information, refer to Limitations of      |
|                  |MM_MCIPOSITIONCHANGE Verification.        |
\-------------------------------------------------------------/</pre>
Position Change Notifications

A MM_MCICUEPOINT line notifies an application that the playlist processor has encountered a ''message''instruction.

<pre class="western">+MM_MCICUEPOINT position %user-parameter</pre>


<pre class="western">/-------------------------------------------------------------\
|Keyword           |Description                               |
|------------------+------------------------------------------|
|position          |Specifies the expected MMTIME position of |
|                  |the first position-change message.        |
|------------------+------------------------------------------|
|user-parameter    |Specifies the user parameter to be        |
|                  |returned. This should be the same as the  |
|                  |return value specified in the             |
|                  |SETPOSITIONADVISE string command. Note    |
|                  |that the return value must be a unique    |
|                  |integer in the range of 1 - 99.           |
\-------------------------------------------------------------/</pre>
'''Note:'''Other notifications cannot be compared because they do not allow for a ''user-parameter''as part of the message, which is essential for the tracking of related notifications.





=== Limitations of MM_MCIPOSITIONCHANGE Verification ===

There are limitations to what you can verify in the P2STRING tool using event notification lines. The MM_MCIPOSITIONCHANGE line requires the use of the &quot;return ''value''&quot; item in the respective string commands. This line also does not provide for timing start point, for example, playing has started. The P2STRING tool can only count the number of messages received for a specific user parameter (used as a key) and check if subsequent messages have positions approximate to the given expected position interval. The script writer has the responsibility to determine how many POSITIONADVISE messages are expected, taking into account the duration of playing, time format, and start position of the play/record. The reference ''position''given in the expected notification line must be in MMTIME units. If the &quot;expected number of messages&quot; parameter is omitted, the tool verifies only the position interval (not the number). In case of scripts where play, seek, or record are used to cover non-monotonic ranges, the tool might report failures on position-advises because it expects each positionadvise to be in the next position interval from the previous message. If the script makes a jump to a position that does not conform to this, the status will be logged as failed.

For example:

<pre class="western">setpositionadvise SomeDevice every 10000 on return 5
+MM_MCIPOSITIONCHANGE 10000 %5
play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages)
seek SomeDevice to 30000 wait
play SomeDevice notify (produces a number of messages starting at 30000)</pre>
The position-change messages are logged as failed, because of the lapse in position interval. A way to handle this situation is to disable the position-change before an explicit position jump is made and enable the same position-advise with a different user parameter.

For example:

<pre class="western">setpositionadvise SomeDevice every 10000 on return 5
+MM_MCIPOSITIONCHANGE 10000 %5
play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages)
setpositionadvise SomeDevice every 10000 off
seek SomeDevice to 30000 wait
setpositionadvise SomeDevice every 10000 on return 6
+MM_MCIPOSITIONCHANGE 10000 %6
play SomeDevice notify (produces a number of messages starting at 30000)</pre>




=== Processing Logic ===

A string command line can be followed by zero to one return value lines, or zero to three notification lines. Note that this is an exclusive OR, meaning that specifying both expected return value and expected notification is not going to give reliable results due to the fact that returned buffer does not become valid prior to the end of the notify message. Also, in case of notify flags, return values are in the procedural interface format rather than in the string interface format.

The MDM will not be able to convert return values to strings for commands processed with the notify flag because media control drivers will be sending their notify messages directly to the application.

Status of each command is determined in two stages. The first stage is at string execution. If the mciSendString function returns an error and there was no =!ERROR reference line in the script following the command string line, the command is considered failed. If a return value was found after mciSendString is processed, the tool will check for expected return and perform comparison of the two. It they do not match, the command is considered failed. In case of an error that is not in the range understood by the mciGetErrorString function, the command is considered failed even if the !ERROR was encountered.

The second stage of the comparison is after a notification is received and after all the commands are issued. If a notification was received and it was successfully compared to the expected notification line, the command is considered successful. If there was no reference notification line, status of the command will not be assigned, unless notify-error was returned. After all the scripts are processed, expected reference notifications will be used to determine if all the notifications were received. The commands that did not receive a notification, and had an expected notification line of the type, are marked failed. Note that command strings are not examined for presence of a notify flag and it is the writer's responsibility to create an expected notify line if it is of importance. In case of expected NOTIFY_SUCCESSFUL messages, all codes other than NOTIFY_ERROR are considered valid. This includes NOTIFY_SUCCESSFUL, NOTIFY_ABORTED and NOTIFY_SUPERSEDED. If any other notify code was specified as expected, and exact match will be checked for. If NOTIFY_ERROR is expected, all errors in the range are verified as passed. There is no facility for verification of an exact error code returned in the notification.





=== Testing Device Drivers ===

Test suites have been provided with this release of the DDK to assist in certifying audio and video device drivers. The test suites provided consist of several test cases. The following sections describe how to:

�Set up the environment for running the test suites

�Run the test suites

�Analyze the test





=== Setting Up the Environment for Running Test Suites ===

Before using the audio or video test suites with the P2STRING tool, do the following:

1.Make sure that OS/2 2.1 and the adapter to be tested are installed.

2.Update the CONFIG.SYS file.

All the test suites use environment variable to determine the location of the input data files. Add the following SET statements to the CONFIG.SYS file.

<pre class="western">SET MMDATA=&lt;path&gt;
SET MMDATA-AUD=&lt;path&gt;
SET TESTDATA=&lt;path&gt;</pre>
The path for MMDATA and MMDATA-AUD must specify the path to the audio input files. For example, your .WAV or .MID files. The path for TESTDATA must specify a path to a temporary working directory that you create.

The following files must be loaded, and their path must be specified in the CONFIG.SYS file:

SETENV.CMD <br />RESETINI.CMD <br />HWCODE.CMD <br />P2STRING.EXE <br />P2S_DLL.DLL

3.Shut down and restart your workstation so the CONFIG.SYS parameters will take effect.

4.Run HWCODE.CMD for each test suite to be tested.

This file is in the ''IBM Developer Connection Device Driver Kit for OS/2''HWCODE.CMD is a REXX command that determines each test case's exact hardware needs and displays the results. The test case's name contains information that HWCODE.CMD uses to make these determinations, so it is important not to change the name of the test case.

The syntax for HWCODE.CMD is:

<pre class="western">HWCODE &lt;Test Case Name&gt;</pre>
'''Note:'''The Test Case Name must include the file name extension. HWCODE.CMD displays the brand and model of audio and video adapters currently supported by OS/2 2.1. The adapter being tested is not listed if it is new , but this information is useful for comparing results based on expected compatibility with other manufactures.

HWCODE.CMD also displays audio and video hardware codes.





=== Hardware Codes ===

The hardware codes are two digit codes. The hyphen (-) in the tables indicate the position of the unspecified digit in the code. For example, if you receive the hardware code 84, you would look in the 8- column and the - 4 column to decipher the hardware code.

Audio Hardware Codes

'''Audio Capture Playback Adapters'''



<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |ACPA                |Number of Cards     |
|                    |                    |Unspecified         |
|--------------------+--------------------+--------------------|
|0-                  |                    |                    |
|--------------------+--------------------+--------------------|
|1-                  |1                   |                    |
|--------------------+--------------------+--------------------|
|2-                  |2                   |                    |
|--------------------+--------------------+--------------------|
|3-                  |3                   |                    |
|--------------------+--------------------+--------------------|
|8-                  |                    |1                   |
|--------------------+--------------------+--------------------|
|9-                  |1                   |1                   |
|--------------------+--------------------+--------------------|
|A-                  |2                   |1                   |
|--------------------+--------------------+--------------------|
|B-                  |3                   |1                   |
|--------------------+--------------------+--------------------|
|G-                  |                    |2                   |
|--------------------+--------------------+--------------------|
|H-                  |1                   |2                   |
|--------------------+--------------------+--------------------|
|I-                  |2                   |2                   |
|--------------------+--------------------+--------------------|
|J-                  |3                   |2                   |
|--------------------+--------------------+--------------------|
|O-                  |                    |3                   |
|--------------------+--------------------+--------------------|
|P-                  |1                   |3                   |
|--------------------+--------------------+--------------------|
|Q-                  |1                   |3                   |
|--------------------+--------------------+--------------------|
|R-                  |3                   |3                   |
\--------------------------------------------------------------/</pre>
'''OEM'''

<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |OEM                 |Number of CDROMs    |
|--------------------+--------------------+--------------------|
|-0                  |                    |                    |
|--------------------+--------------------+--------------------|
|-1                  |OPL0 (original Sound|                    |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-4                  |Sound Blaster 16    |                    |
|--------------------+--------------------+--------------------|
|-5                  |ProAudio Spectrum 16|                    |
|--------------------+--------------------+--------------------|
|-6                  |Sound Blaster Pro   |                    |
|--------------------+--------------------+--------------------|
|-7                  |Any Sound Blaster   |                    |
|--------------------+--------------------+--------------------|
|-8                  |                    |1                   |
|--------------------+--------------------+--------------------|
|-9                  |OPL0 (original Sound|1                   |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-C                  |Sound Blaster 16    |1                   |
|--------------------+--------------------+--------------------|
|-D                  |ProAudio Spectrum 16|1                   |
|--------------------+--------------------+--------------------|
|-E                  |Sound Blaster Pro   |1                   |
|--------------------+--------------------+--------------------|
|-F                  |Any Sound Blaster   |1                   |
|--------------------+--------------------+--------------------|
|-G                  |                    |2                   |
|--------------------+--------------------+--------------------|
|-H                  |OPL0                |2                   |
|--------------------+--------------------+--------------------|
|-K                  |Sound Blaster 16    |2                   |
|--------------------+--------------------+--------------------|
|-L                  |ProAudio Spectrum 16|2                   |
|--------------------+--------------------+--------------------|
|-M                  |Sound Blaster Pro   |2                   |
|--------------------+--------------------+--------------------|
|-N                  |Any SB              |2                   |
|--------------------+--------------------+--------------------|
|-O                  |                    |3                   |
|--------------------+--------------------+--------------------|
|-P                  |OPL0 (original Sound|3                   |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-S                  |Sound Blaster 16    |3                   |
|--------------------+--------------------+--------------------|
|-T                  |ProAudio Spectrum 16|3                   |
|--------------------+--------------------+--------------------|
|-U                  |Sound Blaster Pro   |3                   |
|--------------------+--------------------+--------------------|
|-V                  |Any SB              |3                   |
\--------------------------------------------------------------/</pre>
'''Special Hardware Needs'''

<pre class="western">/-------------------------------------------------------------\
|Hardware Code       |Special Hardware Needs                  |
|--------------------+----------------------------------------|
|W0                  |Pioneer laser disc V80000               |
|--------------------+----------------------------------------|
|W1                  |Pioneer laser disc V4400                |
|--------------------+----------------------------------------|
|W2                  |Pioneer laser disc V4200                |
|--------------------+----------------------------------------|
|W3                  |Pioneer laser disc V4300D               |
\-------------------------------------------------------------/</pre>
Video Hardware Codes

'''VCA'''



<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |VCA                 |Number of Cards     |
|                    |                    |Unspecified         |
|--------------------+--------------------+--------------------|
|4-                  |                    |                    |
|--------------------+--------------------+--------------------|
|5-                  |1                   |                    |
|--------------------+--------------------+--------------------|
|6-                  |2                   |                    |
|--------------------+--------------------+--------------------|
|C-                  |                    |1                   |
|--------------------+--------------------+--------------------|
|D-                  |1                   |1                   |
|--------------------+--------------------+--------------------|
|E-                  |2                   |1                   |
|--------------------+--------------------+--------------------|
|K-                  |                    |2                   |
|--------------------+--------------------+--------------------|
|L-                  |1                   |2                   |
|--------------------+--------------------+--------------------|
|M-                  |2                   |2                   |
\--------------------------------------------------------------/</pre>
'''OEM'''



<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |OEM                 |Number of CDROMs    |
|--------------------+--------------------+--------------------|
|-0                  |Any video capture   |                    |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-1                  |Any video capture   |                    |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-2                  |Any video capture   |                    |
|                    |card and a ProAudio |                    |
|                    |Spectrum 16         |                    |
|--------------------+--------------------+--------------------|
|-8                  |Any video capture   |1                   |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-9                  |Any video capture   |1                   |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-A                  |Any video capture   |1                   |
|                    |card and a ProAudio |                    |
|                    |Spectrum 16         |                    |
|--------------------+--------------------+--------------------|
|-G                  |Any video capture   |2                   |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-H                  |Any video capture   |2                   |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-I                  |Any video capture   |2                   |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
\--------------------------------------------------------------/</pre>
'''Special Hardware Needs'''



<pre class="western">/-------------------------------------------------------------\
|Hardware Code       |Special Hardware Needs                  |
|--------------------+----------------------------------------|
|X0                  |IBM VCA NTSC                            |
|--------------------+----------------------------------------|
|X1                  |Jovian SuperVia NTSC                    |
|--------------------+----------------------------------------|
|X2                  |Jovian QuickVia NTSC                    |
|--------------------+----------------------------------------|
|X3                  |Video Blaster NTSC                      |
|--------------------+----------------------------------------|
|X4                  |IBM VCA  PAL                            |
|--------------------+----------------------------------------|
|X5                  |Jovian SuperVia  PAL                    |
|--------------------+----------------------------------------|
|X6                  |Jovian QuickVia  PAL (WinMovie)         |
|--------------------+----------------------------------------|
|X7                  |Video Blaster PAL                       |
\-------------------------------------------------------------/</pre>




=== Running the Test Suites ===

The suites are run using P2STRING. For more information about P2STRING, see [[00112.htm|AP2/P2STRING Tool]].

To run a device test, do the following:

1.Open an OS/2 window.

2.Run SETENV.CMD.

'''Note:'''Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.

This file is in the ''IBM Developer Connection Device Driver Kit for OS/2''. This command should be run prior to running the first test (each time you open an OS/2 window) because it sets up the audio devices correctly. To run this command, type:

<pre class="western">SETENV</pre>
3.Run RESETINI.CMD prior to each test.

'''Note:'''Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.

This file is in the ''IBM Developer Connection Device Driver Kit for OS/2''. This command resets system connections in the appropriate INI files for audio and video tests to their defaults. To run this command, type:

<pre class="western">RESETINI</pre>
4.Run each test. Each test can be run from the command line and the output is saved in a file for analysis. The P2STRING syntax is:

<pre class="western">P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]</pre>


For more information about running tests from the command line, see [[00117.htm|Starting P2STRING]].

The tests display messages in a message box and might not automatically close the message box when the test finishes. If the test does not close the message box, you need to manually close it. The message box is not closed if P2STRING is waiting for a return value that might or might not be returned. The test has finished processing if the string &quot;Script completed successfully&quot; is displayed at the bottom of the message box. Allow approximately one minute after this message is displayed before manually closing the message box to allow for any late return codes.

'''Note:'''The &quot;Script completed successfully&quot; message does not indicate that all the tests passed. It only indicated the script has finished processing .





=== Analyzing a Device Driver Test ===

After an audio or video test is run, the results of the test are stored in a file with a .IND extension appended to the file name. The media control interface strings that passed are flagged with a PASSED keyword in the return string, and failed strings are flagged with a FAILED keyword.

Those that are flagged as FAILED can be analyzed further. When all strings are passed successfully, the device driver is handling all conditions specified by the test correctly.

'''Note:'''If a string command is supposed to fail and does, the return string is considered PASSED, because the return string matches the expected results.

The following example illustrates how to compare the results file with the test script.

<pre class="western">  TEST SCRIPT  (AUDIO1.P80)


         ############################################
         #                                          #
         #   OPEN THE MIDIPLAYER                    #
         #   WAIT FOR SUCCESSFUL OPEN               #
         #                                          #
         ############################################
         #
 /---&gt;   open sequencer alias midiplayer notify
 |/--&gt;   +MM_MCINOTIFY MCI_NOTIFY_SUCCESSFUL MCI_OPEN #1
 ||      @WAIT_NOTIFY 1 45000
 ||      @WAIT_PASSDEVICE midiplayer
 ||      ############################################
 ||      #                                          #
 ||      #   LOAD AND CUE TYPE1. MID FILE           #
 ||      #   PLAY jesu.mid  FILE AND EXPECT AN      #
 ||      #   ABORT FROM A PAUSE                     #
 ||      #                                          #
 ||      ############################################
 ||      #
 ||  /-&gt; load midiplayer ?MMDATA-AUD?\jesu.mid  wait
 ||  |   cue midiplayer output wait
 ||  |   play midiplayer from 100 to 60000 notify
 ||  |   +MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY
 ||  |   #
 ||  |
 ||  |
 ||  |                 TEST OUTPUT FILE (AUDIO1.LOG)
 ||  |
 ||  |
 ||  |          ****************Opening script file
 ||  |
 ||  |
 ||  |          Thread 1 executing 21 commands.
 \|--|--------&gt; T:1 send string #  1 open sequencer alias midiplayer notify
  \--|--------&gt; EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1
     |     |--&gt; T:1 Notify received for #  1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1
     |     \--&gt; NOTIFY STATUS FOR #1: PASSED
     |          T:1 Notify received MM_MCIPASSDEVICE MCI_GAINING_USE Device ID 1
     |           returned string for #  1: 1
     |          T:1 @WAIT_NOTIFY 1 45000
     |          T:1 @WAIT_PASSDEVICE MIDIPLAYER
     \--------&gt; T:1 send string #  2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait
           |--&gt;  no returned string for #  2.
           \--&gt; NOTIFY STATUS FOR #2: FAILED
                   .
                   .
                   .

                END OF SCRIPT FILE REACHED. 14 COMMANDS SENT

                Waiting for late notifications for 30 sec
                T:1 Notify received for # 14 MM_MCINOTIFY SUCCESSFUL by command MCI_CLOSE ID 1
                NOTIFY STATUS FOR #14: PASSED

                Script completed successfully</pre>
The first command &quot;open sequencer alias midiplayer notify&quot; in the test expects the following results:

<pre class="western">+MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY</pre>
Following the first and second line down in the previous example, you can see that this command passed successfully:

<pre class="western">EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1
T:1 Notify received for #  1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1
NOTIFY STATUS FOR #1: PASSED</pre>
The following lines in the test script are not expecting returned information:

<pre class="western">@WAIT_NOTIFY 1 45000
@WAIT_PASSDEVICE midiplayer</pre>
Therefore, the test output echoes these commands to show they were received .

<pre class="western">T:1 @WAIT_NOTIFY 1 45000
T:1 @WAIT_PASSDEVICE MIDIPLAYER</pre>
However, the &quot;load midiplayer ?MMDATA-AUD?\jesu.mid wait&quot; command did not receive the expected message, and the following is logged to the test file:

<pre class="western">T:1 send string #  2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait
 no returned string for #  2.
NOTIFY STATUS FOR #2: FAILED</pre>
The bottom of the test output file indicates how many commands were processed, it also indicates if it is waiting for late notifications. Depending on the test, and the devices being tested, expected notifications might not always arrive on time or in the order expected. If a notification does not arrive when expected, it can arrive later if the device driver has not failed.

This is especially important on multi-threaded or multi-process processing. The more complicated the test (for example stress testing the device driver with multiple devices), the more difficult it is to decipher the output file. You will have to keep track of each thread or process separately to determine the results of the test.





=== Ultimotion Data Stream Specification ===

Advances in microprocessor power, data storage, and compression technology have provided key technologies for creating and playing digital video data on personal computers. The high capacity disk drives and CD-ROMs satisfy the large storage needs of digital video data. Additionally, today's more powerful microprocessors provide sufficient power to handle digital video data in real time. When these advances are combined with image compression techniques, the result is a powerful integration of video and the personal computer.

Several compression algorithms are currently in use throughout the industry . Some of these algorithms are numerically intensive and use additional video hardware to compress and decompress the digitized video. Others are less numerically intensive and can be handled by software running on the main CPU and still maintain sufficient frame rates to provide motion. These are referred to as ''software-only''algorithms. While software-only techniques are attractive due to their low cost, the video quality of these algorithms is typically lower than the hardware-based algorithms. Consequently, producers of digital video data struggle with trading off lower quality and cost of software-only techniques for the higher quality and cost of hardware-assisted video. Ultimotion* provides a motion video compression technique capable of producing a high level of quality in a software-only playback environment.

=== Overview of Ultimotion Video Compression ===
Decompression (playback) of Ultimotion video is possible with very low computational complexity to enable real-time playback in a software-only environment. The &quot;nominal Ultimotion movie&quot; is defined as 320 x 240, 15 frames per second at a 150KB per second data rate. This movie can be played on at least a 25 MHz 80386 microprocessor. Systems with faster microprocessors are capable of higher frame rates and larger output image sizes.

Compression (recording) of Ultimotion video can be performed with a range of computational complexity. In a software-only environment using frame- grabber hardware, Ultimotion video can be compressed either in real-time or asymmetrically in conjunction with frame-step recording.

Ultimotion real-time compression provides instant video turn-around at a very low cost. The most common quality type can be used to produce 160 x 120 videos at 15 frames per second with a 25 MHz 80486 microprocessor. A larger frame size can be used to produce 320 x 240 videos at 8 frames per second. The quality level is selectable to attain different data rates. Slower systems may also be used for real time capture or record, but the frame rates will be lower.

Asymmetric compression provides the most compression and quality, but must be used in conjunction with frame-step capture, or raw input source files. With a 25 MHz 80486 microprocessor, 320 x 240 frames can be compressed in one to four seconds. Specialized capture or compression hardware will enable real-time capture with the same quality level now attained through asymmetric compression.





=== Scalability ===

Ultimotion is a playback-time scalable video data stream. While the frame rate and output image size (resolution) are set when the video is created, the characteristics of a playback scalable video are modified during playback according to the capabilities of the playback platform. These playback-platform capabilities depend on the type of microprocessor, data bandwidth, display driver, and video adapter available during playback. Based on the characteristics of these components, the output quality of a single Ultimotion video stream can be &quot;scaled&quot; to the playback platform.





=== Processor Independence ===

In deriving the Ultimotion data stream, care was taken to balance the requirements of software-only and hardware-assisted decompression. The resulting data stream:

�Uses byte-oriented data organization and simple integer arithmetic (that is, no multiplication or division) so that non-computationally intensive decompression algorithms can be used.

�Organizes the data for efficient processing of unwanted data when being scaled during playback.

Data structures are organized for hardware-assisted techniques wherever feasible but do not utilize any particular processor instruction capability .





=== Playback Characteristics ===

While Ultimotion is a runtime scalable data stream, the magnitude that the data stream will &quot;scale&quot; is determined by the amount of information that is encoded in the data stream when it was created. That is, the amount of data placed in the stream at creation time determines the &quot;maximum&quot; playback characteristics that a particular stream can achieve. In turn, the processing capabilities of the playback system determine how much of the data can be processed and presented during playback. Therefore, the playback characteristics of a given video are a function of the data put into the video by the author ''and''the processing capabilities of the playback system.

The factors affecting the data stream at creation time are:

�Resolution - width and height of video <br />�Frame duration - frequency at which frames are to be displayed <br />�I-frame rate - frequency at which reference frames are to occur <br />�Data rate - average amount of data allowed for an interval of video

Factors affecting the playback of a video are:

�Processing power of the CPU <br />�Throughput of data storage (for example, CD-ROM, hard disk, and LAN) <br />�Efficiency of the display subsystem

'''Resolution Scalability'''

Resolution of a video determines how much spatial information is in a video image, as well as the &quot;normal&quot; playback size. Ultimotion video compression enables the output image size to be efficiently scaled up or down as it is decompressed, based on user preference or application requirements. Scaling down the output image size enables more efficient playback on slower systems.

'''Frame Rate Scalability'''

Frame duration for the frames in a video is usually referred to as frame rate. A frame compressed without regard to a prior frame uses intraframe compression and is called an ''I-frame''. A frame compressed by considering only what has changed from a prior frame uses temporal compression and is called a ''delta frame''. I-frames are a snapshot in time of the video. Delta frames show only what changed. The I-frame rate of a video is the frequency that I-frames occur in the data stream.

The I-frame rate affects several characteristics of a video stream:

�Data rate <br />�Quality of motion during scanning <br />�Performance of seek operations <br />�Ability to maintain smooth motion when frames are dropped to maintain audio synchronization <br />�Image re-paint time in a windowing system where no backup saving is used during clipping

Since I-frames contain the compressed data of the entire image, they are typically larger than delta frames. Ultimotion data streams that mix I- frames and delta frames:

�Reduce throughput requirements with smaller delta frames <br />�Provide points in the stream at which the entire image exists (good for seeking and scanning) <br />�Provide points in the video stream at which artifacts are repaired (with I -frames)

Generally, an I-frame rate of one I-frame every one or two seconds provides the best results.

'''Color Scalability'''

Ultimotion compression algorithms store images in a YUV direct color space. This color space is mapped at playback time to the number of colors available on the playback system. This avoids the need to have different versions of video content to fully exploit varying hardware capabilities.





=== Playback Platform Considerations ===

'''Direct Output'''

When decompressed, the Ultimotion data stream can produce either partial or complete video frames. The technique chosen to display these frames varies from platform to platform and largely depends on the display subsystem of the platform. Some systems allow a decompressor to access the display buffer directly where the decompressor may only update changed information. Others require changed information in full frames. The resulting performance characteristics of playback on various platforms is dependent on the efficiency of the display subsystem.

'''Window Clipping'''

In support of direct output in a windowing environment, Ultimotion decompression is well-suited for enabling clipping in the decompressor.





=== How Ultimotion Video Compression Works ===

The data stream combines several techniques to provide both temporal and spatial compression. These techniques include the following, which will be discussed in more detail in this section:

�Variable chrominance subsampling <br />�Luminance transition coding <br />�Statistical luminance image coding





=== Interframe versus Intraframe Compression ===

While the data stream supports both interframe and intraframe compression, no specific distinction is made between frame types. An intraframe compressed frame is one that does not contain any unchanged data. This does not preclude the file format from making such a distinction, as in the Audio/Video Interleaved (AVI) file format. Capture or compression software generally enables periodic insertion of intraframe compressed video frames.





=== Format of Encoded Video Frame Data ===

During video compression, each video frame is decomposed into non- overlapping square ''blocks'', nominally of 8 x 8 pixels. Blocks in turn are decomposed into ''quadrants'', nominally of 4 x 4 pixels. The quadrants in a block are considered to be ordered in a counter-clockwise direction, beginning with the upper-left quadrant. [Artwork not shown]

'''Blocks'''

The format of the encoded video frame data is the sequence of all blocks in the frame, each encoded as shown in the following figure, and ordered in a raster scan of the grid of blocks in the video frame. The data for a block begins with a one-byte ''block header''that defines the interpretation of the data that follows for the block and the quadrants contained in the block.

While the block size is variable on output, the preferred output block size is 8 x 8 pixels, which results in a direct mapping of some encoding types ( statistical).

The following figure shows the format for each encoded block used to represent the decomposed frame.

<pre class="western">/---------------------------------------\
|XXXXXXXX|   Encoded Block              |
\---------------------------------------/
                 OR
/---------------------------------------\
|XXXXXXXX|Quad 1  Quad 2  Quad 3  Quad 4|
\---------------------------------------/
  Header      Four Encoded Quadrants</pre>
'''Color Space'''

The data stream uses a direct color space; that is, no in-stream palettes or lookup tables are used. The color space used provides 6 bits of luminance and 8 bits of chrominance (6Y 4U 4V). The encoding of chrominance is performed by quantizing a portion of the dynamic range of the U and V components. The RGB conversion is performed using the following equations, which assume an RGB 5-6-5 representation:

<pre class="western">        Y  = ((0.299R + 0.2935G + 0.114B) x 2.037) + 0.5
        U  = (((-0.169R - 0.163G + 0.500B) x 8.226)/6.375) + 5
        V  = (((0.500R - 0.206G - 0.081B) x 8.226)/7.500) + 6</pre>
The value of Y is restricted to 0 through 63 and the values of U and V are restricted to 0 through 15.





=== Variable Chrominance Subsampling ===

The chrominance value for each quadrant is determined by taking a weighted average of the chrominance values of the pixels in the quadrant. The chrominance values for each quadrant in the block are then compared with the chrominance values for other quadrants in the block, and if the values are within a threshold ''t''of each other, the chrominance of the entire block is considered to be perceptually similar, and a single chrominance value is used for the entire block. This results in this block of the image being sampled at a low frequency. If, on the other hand, the chrominance values for the quadrants in the block differ by more than ''t'', the block is considered to contain perceptually dissimilar colors, and a unique chrominance value is used for each quadrant in the block. This results in this block of the image being sampled at a high frequency.

'''Chrominance Modes'''

The data stream uses a variable chrominance subsampling mechanism. Chrominance data appears in the data stream with a varying frequency depending on the ''chrominance mode'':

�Normal chrominance mode

This is the default mode. A single chrominance value (one byte) immediately follows the block header (except in the case of a completely unchanged block) and that chrominance value is used for the entire block.

�Unique chrominance mode

This mode is entered whenever chrominance subsampling fails; that is, using a single chrominance value for an entire block results in &quot;chrominance bleeding&quot; artifacts. In this mode, the block header is not followed by a chrominance value. Instead, each quadrant encoding includes a unique chrominance value.

�Single unique chrominance

Single unique chrominance is signaled by an escape value and indicates that a unique chrominance mode is used for the next block only. See [[00145.htm|Escape Values]].





=== Luminance Transition Coding ===

Luminance transition coding (LTC) is based on the reduction of variation in luminance of a region of an image to a single direction. Each region of the image is analyzed to correlate individual luminance values and determine the direction in which the maximum luminance change is occurring. Sample values are then determined by taking the average number of pixels perpendicular to this direction. The luminance values within the region can then be mapped to one of a predetermined set of luminance values based on various functions of increasing luminance. These functions approximate commonly occurring luminance variations in natural images.

The resultant encoding of the region is then compared with the uncompressed image data for the region. The error (in luminance space) is calculated for use in comparing with other encoding types. The selection of an encoding type is based on the following two considerations: (1) comparison of the errors of the different types (where the error as defined above is inversely correlated to the quality of the representation) and (2) the amount of data each type consumes as allowed by the amount of compression to be obtained.

'''One-Byte Luminance Transition Region Encoding'''

The data for a one-byte encoding consists of a single luminance value and 2 bits that indicate a direction of increasing luminance of one step, if any. The one-byte encoding is useful because regions that have the same luminance value (known as homogeneous regions), or only a very small change in luminance, are common and should be encoded with as little data as possible.

'''Two-Byte Luminance Transition Region Encoding'''

The data for a two-byte encoding consists of the direction of ''increasing''luminance and a transition index value that specifies a base Y value, a delta Y value, and a transition function. The transition index is the index into a table which defines the common set of four byte-transitions. The derivation of this index value is described later.

'''Four-Byte Luminance Transition Region Encoding'''

The data for a four-byte encoding consists of a direction of luminance change and four luminance sample values along the specified direction. The four-byte encoding is useful for regions in which the changes in luminance cannot be accurately mapped to the set of predetermined luminance values used in the two-byte encoding. Note that the specified direction (angle) does not include the opposite directions (ñ 180 degrees) because the luminance values need not be increasing (a requirement of the transition index). Thus the opposite directions are implied by the use of the four luminance values.





=== Format of Block Header ===

The encoding for a block begins with a ''block header''specifying how the four quadrants it represents have been encoded. In addition to specifying these encoding types, certain values of the block header are reserved as escape values that contain control information about the interpretation of the data stream. The possibilities for processing a block as specified by the block header fall into two basic categories:

�Quadrant encodings

Quadrant encodings specify that the block is comprised of four quadrants, NW, SW, SE, and NE. Each quadrant in turn is separately encoded with a quadrant encoding type. Quadrants in a block are encoded independently, and may use different quadrant encoding types, with some restrictions which are described later.

�Block header escape

Rather than indicate the encoding type for a block and its respective quadrants, certain values are reserved as escape values to enable special processing of the data stream.

A block encoding is encoded using a one-byte block header followed by an encoding type. The following figure shows the format for a block encoding.

<pre class="western">/---------------------------------------\
|XXXXXXXX|  BLOCK ENCODING DATA         |
\---------------------------------------/
  Header     Encoded Quadrants</pre>
A quadrant encoding block uses the two left-most bits of the block header to specify how the first quadrant in the stream was encoded. Similarly, the next two left-most bits of the block header specify how the next quadrant was encoded, and so on. The following figure shows the format for a quadrant block.

<pre class="western">/----------------------------------------------\
|Q1Q2Q3Q4|COLOR  QUAD 1  QUAD 2  QUAD 3  QUAD 4|
\----------------------------------------------/
 Header    Four Quadrant Encodings</pre>
The specification of the block header bits depends on the current stream interpretation mode. This mode determines which set of four encoding types is used when a block is decomposed into quadrants. The stream interpretation mode can be switched anywhere within a frame. The stream interpretation mode defaults to mode 0 at the start of each frame.

The following combination of quadrant types are defined for mode 0 stream interpretation:

�00: Unchanged quadrant <br />�01: Homogeneous/shallow LTC quadrant <br />�10: LTC quadrant <br />�11: Statistical/extended LTC quadrant

The following combination of quadrant types are defined for mode 1 stream interpretation:

�00: Unchanged quadrant <br />�01: Homogenous quadrant <br />�10: Subsampled 4-luminance quadrant <br />�11: 16-luminance quadrant





=== Quadrant Encoding Types ===

Encoding types used when a block is comprised into quadrants are described here. All the quadrants of a block share a single 8-bit chrominance value unless unique chrominance mode is being used, in which case each of the quadrant encodings in a block are preceded by a unique chrominance value.

'''Unchanged Quadrant'''

The data for the quadrant is unchanged from the previous frame and no further data is encoded. Note that a block with four unchanged quadrants is the same as an unchanged block which contains no chrominance value. The following figure shows how the encoded data is organized for a block containing one changed quadrant and three unchanged quadrants.

<pre class="western">/-------------------------------\
|00 00 01 00|CHROMINANCE|QUAD 3 |...
\-------------------------------/
 Block Header          One Encoded Quadrant</pre>
Decoding Tips

To decode an unchanged quadrant:

1.Move pointers in the output data to the next quadrant of the block. <br />2.Continue processing the next two bits of the block header.

Compression attained with this quadrant encoding is 0.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant. A completely unchanged block (4 unchanged quadrants) will attain a compression level of 0.125 bits per pixel, as no chrominance information is encoded for the block.

'''Luminance Transition Coding Quadrant'''

The data for the quadrant is described as an angle of direction of increasing luminance and an index indicating the luminance sample values along that direction. The delta Y values are distributed to provide lower quantization in shallow gradients. The following figure shows how the encoded data is organized for an LTC quadrant.

<pre class="western">/----------------------------------------------------\
|xx 10 xx xx|CHROMINANCE| QUAD 1 | AAAA YDIST index  |
\----------------------------------------------------/
Block Header Shared                Luminance transition
             Chrominance</pre>
The quadrant is encoded as follows:

�Four bits representing angle of direction of increasing luminance (0 indicates increasing luminance left to right - 0 degrees - with subsequent angles increasing in a counter-clockwise direction at increments of 22.5 degrees). <br />4 bits Angle of Direction <br />0000 0 degrees <br />0001 22.5 degrees <br />0010 45 degrees

<pre class="western">.
. 
. </pre>
<br />1111 337.5 (-22.5) degrees <br />�12 bits luminance transition index

Decoding Tips

To decode this quadrant:

1.Determine the luminance values to use for the quadrant by performing a table lookup. <br />2.Interpret the direction bits and reverse luminance values if angle value is greater than 7. <br />3.Using the shared chrominance for the block plus the 6 bits of the first luminance, convert the resulting color to the target color space. <br />4.Using the direction bits as a vector, store the color in the appropriate positions of the quadrant. This can be done with eight output routines that map the luminance values into patterns for the first eight angles. The remaining eight angles are the opposite directions from the first eight, and are covered by reversing the luminance values. <br />5.Convert the remaining Y values and store in appropriate positions in the quadrant.

Compression attained with this quadrant encoding is 1.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.

'''Statistical Pattern/Extended LTC Quadrant'''

The first bit of the encoding determines whether the data is a statistical pattern or an extended LTC encoding. If the first bit is 0, the data for the quadrant is described as two luminance values Y1 and Y2, and a pattern specifying the distribution of the two luminance values among the pixels in the quadrant. The following figure shows how the encoded data is organized for a statistical quadrant.

<pre class="western">/--------------------------------------------------------\
|xx 11 xx xx|CHROMINANCE| QUAD 1 | Pattern | 00 Y1 00 Y2 |
\--------------------------------------------------------/
Block Header Shared                Pattern  Luminance Values
             Chrominance</pre>
The quadrant is encoded as follows:

�16 bits of pattern in raster scan order (MSB = 0) <br />�2 bits undefined (decoder must mask) <br />�6 bits Y1 <br />�2 bits undefined (decoder must mask) <br />�6 bits Y2

Decoding Tips

To decode this quadrant:

1.Convert the two luminance values to the output color space using the chrominance for the block or the quadrant, as defined by the current chrominance mode. <br />2.Output the two colors into pixels in the quadrant as defined by the pattern. The color obtained by converting Y1 is output wherever the corresponding pattern bit is 0, and the color obtained by converting Y2 is output wherever the corresponding pattern bit is 1.

The following figure shows how the encoded data is organized for an Extended LTC quadrant.

<pre class="western">/------------------------------------------------------------------\
|xx 11 xx xx|CHROMINANCE| QUAD 1 |1| AAA | Y1 | Y2 | 00 Y3 | 00 Y4 |
\------------------------------------------------------------------/
Block Header Shared                  Angle    Luminance Values
             Chrominance</pre>
The quadrant is encoded as follows:

�1 bit = 1

�3 bits angle 0-157.5 degrees ( 000 = 0 degrees, 22.5 degree increments)

�6 bits Y1

�6 bits Y2

�2 bits undefined (decoder must mask)

�6 bits Y3

�2 bits undefined (decoder must mask)

�6 bits Y4

Decoding Tips

To decode this quadrant:

1.Shift the luminance values into the same positions that are obtained by the luminance transition index lookup. <br />2.Enter the appropriate output routine in the LTC quadrant processing based on the angle specified. (Note that only eight angles are encoded. Because individual Y values are uniquely specified, each angle + 180 degrees is implied by reversing the ordering.)

'''Format of Homogeneous Quadrant/Shallow Gradient Quadrant'''

An encoded ''homogeneous/shallow gradient quadrant''is specified by its corresponding two bits in the block header and a luminance value. The following figure shows how the encoded data is organized for a decomposed block whose second quadrant is a homogenous/shallow gradient.

<pre class="western">/--------------------------------------------\
|xx 01 xx xx|CHROMINANCE| QUAD 1 | ssLL LLLL |
\--------------------------------------------/
Block Header Shared                Luminance
             Chrominance</pre>
The quadrant is encoded as follows:

�2 bits representing Y delta and angle of direction of increasing luminance (00 indicates constant luminance, and values 01, 10, and 11 specify luminance increasing one level across the quadrant in the specified direction).

2 bits Y delta, Angle of Direction <br />00 0, N/A <br />01 1, 45 degrees <br />10 1, 135 degrees <br />11 1, 270 degrees

�Six bits Y

Decoding Tips

To decode this quadrant:

1.Using the shared chrominance value for the block, use the luminance value Y and convert the YUV color to the target color space. <br />2.If angle/delta is 0, store the target color in the entire quadrant. <br />3.If angle/delta is not 0, perform a second color space conversion using Y +1 as the luminance value, and output the two colors with an error diffused density pattern in the direction specified. <br />4.Increment output pointers to the next quadrant in the block. <br />5.Move to the next quadrant in the encoded stream.

Compression attained with this quadrant encoding is 2.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.

'''Subsampled 4-Luminance Quadrant'''

An encoded ''subsampled 4-luminance quadrant''is specified by its corresponding two bits in the block header and four luminance values. When decoded to an 8 x 8 block size, this quadrant encoding type results in one color value per 2 x 2 pixel region in the quadrant. The following figure shows how the encoded data is organized for a block whose second quadrant is a Subsampled 4-luminance quadrant.

<pre class="western">/--------------------------------------------------------------------\
|xx 10 xx xx|CHROMINANCE| QUAD 1 | 1111 1122 | 2222 3333 | 3344 4444 |
\--------------------------------------------------------------------/
Block Header Shared                Four Luminance Values
             Chrominance</pre>
The quadrant is encoded as follows:

�6 bits Y1

�6 bits Y2

�6 bits Y3

�6 bits Y4

Decoding Tips

To decode this quadrant:

1.Using the shared chrominance value in this quadrant and the first luminance value (Y1), convert the YUV color to the target color space. <br />2.Store the output color in the corresponding 2 x 2 area of the quadrant. <br />3.Move output pointers to the next 2 x 2 of the quadrant in the order NW, NE, SW, SE. <br />4.Repeat the last 3 steps for each luminance in the encoded stream.

Compression attained with this quadrant encoding is 1.75 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.

'''16-Luminance Quadrant'''

An encoded ''16-luminance quadrant''is specified by its corresponding two bits in the block header and 16 luminance values. When decoded with an 8 x 8 block size, this quadrant encoding contains one color value per pixel in the quadrant. The following figure shows how the encoded data is organized for a block whose second quadrant is a 16-luminance quadrant.

<pre class="western">/--------------------------------------------------------------------\
|xx 11 xx xx|CHROMINANCE| QUAD 1 | 1111 1122 | 2222 3333 | 3344 4444 | ....
\--------------------------------------------------------------------/
Block Header Shared                16 Luminance Values
             Chrominance</pre>
The quadrant is encoded as follows:

�6 bits Y1

�6 bits Y2

�6 bits Y3

�6 bits Y4

<pre class="western">       .
       .
       .</pre>
�6 bits Y16

Decoding Tips

To decode this quadrant:

1.Using the shared chrominance value in this quadrant and the first luminance value (Y1), convert the YUV color to the target color space. <br />2.Store the output color in the corresponding pixel of the quadrant. <br />3.Repeat the last two steps for each pixel in the quadrant.

Compression attained with this quadrant encoding is 6.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.





=== Escape Values ===

Block headers with a value of 01110xxx are used as escape values, used to specify both block encoding types and data stream interpretation escape values. The following data stream interpretation escape values are defined :

�Normal/unique chrominance mode toggle

This escape toggles the chrominance mode between normal and unique.

�Single unique chrominance mode

This escape causes the following block to be interpreted in unique chrominance mode. The current chrominance mode is unchanged.

�Frame guard byte

For efficiency, decoder implementations may choose not to bounds check addressing into the source data buffer. If the source buffer contains invalid data, an access violation might occur. Additionally, invalid data might be decoded as valid data without any means of software detection. Both of these problems are addressed with the &quot;guard byte&quot; value.

At least one guard byte always appears at the end of a coded frame, and is encoded in the stream. If the byte immediately following the last block encoding for a frame is not equal to this value, it is considered to be an error. As it is highly improbable that a buffer containing invalid data will be decoded and the above condition still met, decoding of invalid source data can be detected in this way.

If a guard byte value is encountered as an escape before the end of the frame, it is also considered to be an error. It is possible to stop a decoder from over-reading with invalid data by appending 64 bytes (the size of the largest block encoding) equal to 73H (the frame guard byte value) to the end of the buffer. A decoder interpreting a stream will then encounter a guard byte before the end of the buffer is overrun.

�Unchanged block run

This escape indicates a number of blocks are completely unchanged. The byte following the escape indicates the total number of blocks to skip. While it is perfectly valid to have consecutive unchanged blocks encoded with block header values of zero, it should be noted that for compression, three or more consecutive unchanged blocks should be encoded as an unchanged block run. Also, since two consecutive unchanged blocks may be encoded as an unchanged block run in the same space as zero block header values, an encoder can establish an unchanged run in the output data stream whenever two consecutive unchanged blocks are encountered.

�General stream control escape

This escape provides a generalized escape mechanism for more escapes than permitted by the 3-bit direct escape in the byte header. This escape is followed by a 1-byte control value. The following generalized escapes are defined:

-Enable stream interpretation mode 0 <br />-Enable stream interpretation mode 1

Note that since block header values 01110xxx are reserved as escape values, quadrant encoding combinations that would produce a block header value with any of these eight values are not allowed and must be altered to other encodings by the compressor.





=== Predetermined Luminance Transitions ===

A static set of luminance transitions across a region are defined. Seven types of predetermined transitions are defined for increasing luminance:

1.Linear

The luminance level increases at a constant rate across the region.

2.Low-contrast edge at 1/4 block width from low-luminance edge

The luminance level changes at an edge that is perpendicular to the direction of increasing luminance at a point where the area of the region following the edge is three times the area of that preceding the edge. The change in luminance is not instantaneous, analogous to a blurry transition.

3.Low-contrast edge at 1/2 block width from low-luminance edge

Same as above, but with the change occurring at the point where the areas of the region on either side of the edge are equal.

4.Low-contrast edge at 3/4 block width from low-luminance edge

Same as above, but with the change occurring at the point where the area of the region preceding the edge is three times the area of that following the edge.

5.High-contrast edge at 1/4 block width from low-luminance edge

The luminance level changes at an edge that is perpendicular to the direction of increasing luminance at a point where the area of the region following the edge is three times the area of that preceding the edge. The change in luminance is instantaneous, analogous to a sharp, well defined edge.

6.High-contrast edge at 1/2 block width from low-luminance edge

Same as above, but with the change occurring at the point where the areas of the region on either side of the edge are equal.

7.High-contrast edge at 3/4 block width from low-luminance edge

Same as above, but with the change occurring at the point where the area of the region preceding the edge is three times the area of that following the edge.

The pre-determined luminance transitions are comprised of a subset of the total possible luminance changes in the range 0 through 63 for each of the transition types as follows:

�Linear

Total Y delta = 2 3 4 5 6 7 8 11 14 17 20

�Low-contrast Edge

Total Y delta = 4 5 6 7 8 11 14 17 20 23 26 29 32 36

�High-contrast Edge

Total Y delta = 6 8 11 14 17 20 23 26 29 32 35 40 46

These selections of allowable Y delta values in two-byte Luminance Transition region encodings accomplish several objectives:

�When combined with the seven transition types at all 64 initial luminance levels, the total number of valid transitions (those in which the Y delta value added to the initial luminance level does not exceed the maximum luminance level of 63) is 4096, which can be encoded in 12 bits in the two- byte encoding.

�Regions with small changes in luminance (for example, &lt;= 8) can be encoded with single luminance level precision. Regions with small changes in luminance are more common than regions with extreme changes.

�Regions with larger changes in luminance (8 &lt; x &lt; 32) can be represented with an edge-to-edge error not exceeding one luminance level.

�Extreme changes in luminance (32 &lt; x &lt; 50) can be represented in two-byte encodings if required by data rate constraints, although with some potential loss in quality as the extreme Y delta values are more highly quantized.

The following additional characteristics are exploited in the selection of allowable Y delta values for each transition type:

�Transitions with Y delta values less than two are encoded with the one- byte encoding (resulting in a quantized direction).

�Edge transitions with Y delta values less than 4 are deemed perceptually similar to a linear transition.

�Edge transitions with Y delta values less than 6 are deemed perceptually similar with regard to edge type, that is, low or high contrast.

�Transitions with Y delta values greater than 20 tend to be non-linear, that is, usually include an edge, and are coded only as such

�Luminance changes greater than 50 are extremely rare and can be quantized with little perceptible quality loss.

The luminance transition index is produced by enumerating all valid transitions that are combinations of initial Y values of 0 through 63 and transition types with Y delta values as listed above. The following code fragment illustrates how these combinations are enumerated:

<pre class="western">   for (Y1 = 0, Y1 &lt;= 63, Y1++) {
      for (Y2 = Y1, Y2 &lt;= 63, Y2++) {
         Ydelta = Y2 - Y1;
         if (Ydelta == &lt;valid linear transition Y delta value&gt;)
            &lt;enumerate linear transition&gt;;
         if (Ydelta == &lt;valid low-contrast edge transition Y delta value&gt;)
         {
            &lt;enumerate low-contrast edge at 1/4 transition&gt;;
            &lt;enumerate low-contrast edge at 1/2 transition&gt;;
            &lt;enumerate low-contrast edge at 3/4 transition&gt;;
         }
         if (Ydelta == &lt;valid high-contrast edge transition Y delta value&gt;)
         {
            &lt;enumerate high-contrast edge at 1/4 transition&gt;;
            &lt;enumerate high-contrast edge at 1/2 transition&gt;;
            &lt;enumerate high-contrast edge at 3/4 transition&gt;;
         }
      }
   }</pre>




=== Data Stream Escape Value Constants ===

Escape values defined in the data stream are one-byte values, in the range 70H - 77H (01110xxx).





=== General Stream Control Escape - 70H ===

This escape is used to imbed control information in the stream. It is followed by a single byte value containing the control information.

'''Stream control byte values'''

�Set stream interpretation mode 0 - 00H

Stream interpretation mode 0 block header quadrant decomposition cases:

1.00: Unchanged quadrant

2.01: Homogenous/shallow LTC quadrant

3.10: Luminance transition coding (LTC) quadrant

4.11: Statistical/extended LTC quadrant

�Set stream interpretation mode 1 - 01H

Stream interpretation mode 1 block header quadrant decomposition cases:

1.00: Unchanged quadrant

2.01: Homogenous/shallow LTC quadrant

3.10: Subsampled 4-luminance quadrant

4.11: 16-luminance quadrant





=== Single Unique Chrominance Block Escape - 71H ===

This escape signals that the next block contains unique chrominance values. The chrominance mode (normal or unique) is unchanged. If the current chrominance mode is unique, this escape has no effect and is ignored.





=== Normal/Unique Chrominance Mode Toggle Escape - 72H ===

This escape causes normal chrominance mode to be entered if the current mode is unique chrominance mode, and causes unique chrominance mode to be entered if the current mode is normal chrominance mode.





=== Frame Guard Byte Value - 73H ===

This escape assists the decoder in determining if invalid data has been encountered in the input stream. See [[00145.htm|Escape Values]]for a more detailed explanation.





=== Unchanged Block Run Escape - 74H ===

This escape value indicates some number of completely unchanged blocks. The number of unchanged blocks follows the escape in a single byte, and as such , is limited to 255.





=== Reserved Escape Values - 75H, 76H, 77H ===

These escape values are reserved.





=== DDCMD Messages ===

The device driver commands are an interface used by a stream handler to communicate with a physical device driver. This interface uses the inter- device driver communication (IDC) mechanism provided by OS/2 AttachDD DevHelp. The stream handler must attach to the device driver using AttachDD DevHelp to receive the DDCMD entry point address of the device driver. This must be done prior to issuing any DDCMDs. Some device drivers also might require that a DosOpen call be used to open the device driver before it can be used through the AttachDD entry point.

The DDCMDs are provided through a single entry point, [[00155.htm|DDCMDEntryPoint]], which accepts a parameter structure on input.

<pre class="western"> typedef ULONG (FAR*PSHDFN)        (PVOID pParmIn);
 typedef ULONG (FAR*PDDCMDFN)      (PVOID pParmIn);</pre>
For the Ring 3 DLL interface, all pointers are 0:32 linear; for Ring 0 stream handlers all pointers are 16:16 far pointers to enable the 16-bit device driver model to be used. The following list contains the message numbers for all DDCMDs. It should be used in the ''ulFunction''field, of the parameter structure passed on the call, to indicate which function is being requested by the stream handler.

<pre class="western">/--------------------------------------------------------------\
|Message |Message                   |Description               |
|Number  |                          |                          |
|--------+--------------------------+--------------------------|
|4L      |DDCMD_CONTROL             |Performs a device-specific|
|        |                          |command.                  |
|--------+--------------------------+--------------------------|
|6L      |DDCMD_DEREG_STREAM        |Removes a stream instance |
|        |                          |from a device driver.     |
|--------+--------------------------+--------------------------|
|1L      |DDCMD_READ                |Performs a read from the  |
|        |                          |device into a buffer.     |
|--------+--------------------------+--------------------------|
|5L      |DDCMD_REG_STREAM          |Registers a stream        |
|        |                          |instance with a device    |
|        |                          |driver.                   |
|--------+--------------------------+--------------------------|
|0L      |DDCMD_SETUP               |Performs a device-specific|
|        |                          |stream instance setup.    |
|--------+--------------------------+--------------------------|
|3L      |DDCMD_STATUS              |Requests status from the  |
|        |                          |device.                   |
|--------+--------------------------+--------------------------|
|2L      |DDCMD_WRITE               |Performs a write from a   |
|        |                          |buffer to the device.     |
\--------------------------------------------------------------/</pre>




=== DDCMDEntryPoint ===


-----

Select an item:

<pre class="western">Syntax
Parameters 
Returns 
Remarks 
Glossary </pre>

-----

This function enables device driver stream handlers to interface with the hardware physical device driver (PDD).

<pre class="western">#include &lt;os2me.h&gt;

PDDCMDCOMMON    pCommon;  /*  Pointer to DDCMDCOMMON. */
ULONG           rc;       /*  Return codes. */

rc = DDCMDEntryPoint(pCommon);</pre>




=== DDCMDEntryPoint - Syntax ===

This function enables device driver stream handlers to interface with the hardware physical device driver (PDD).

<pre class="western">#include &lt;os2me.h&gt;

PDDCMDCOMMON    pCommon;  /*  Pointer to DDCMDCOMMON. */
ULONG           rc;       /*  Return codes. */

rc = DDCMDEntryPoint(pCommon);</pre>




=== DDCMDEntryPoint Parameter - pCommon ===

'''pCommon'''([[00756.htm|PDDCMDCOMMON]]) - input A pointer to a DDCMD message-specific input parameter block. See [[00756.htm|DDCMDCOMMON]].





=== DDCMDEntryPoint Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) - returns Return codes indicating success or the type of failure :

NO_ERROR Successful.

ERROR_INVALID_FUNCTION Invalid function requested.

FAILURE A DDCMD message-specific error return code.





=== DDCMDEntryPoint - Parameters ===

'''pCommon'''([[00756.htm|PDDCMDCOMMON]]) - input A pointer to a DDCMD message-specific input parameter block. See [[00756.htm|DDCMDCOMMON]].

'''rc'''([[00998.htm|ULONG]]) - returns Return codes indicating success or the type of failure :

NO_ERROR Successful.

ERROR_INVALID_FUNCTION Invalid function requested.

FAILURE A DDCMD message-specific error return code.





=== DDCMDEntryPoint - Remarks ===

Device driver stream handlers communicate with the hardware PDD through the DDCmdEntryPoint. This is accomplished through the use of Device Driver Command (DDCMD) messages, which enable a stream handler to request a PDD to perform functions such as starting, stopping, or resuming operation of a device. This interface uses the IDC mechanism provided by the ATTACHDD DevHelp function. The stream handler must attach to the device driver to receive the DDCMD entry point address of the device driver. This function is performed prior to issuing device driver command messages.





=== DDCMDEntryPoint - Topics ===

Select an item:

<pre class="western">Syntax
Parameters 
Returns 
Remarks 
Glossary </pre>




=== DDCMD_CONTROL ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message performs a device-specific command.



'''pParmIn'''([[00759.htm|PDDCMDCONTROL]]) A pointer to a [[00759.htm|DDCMDCONTROL]]data structure. The ''pParm''and ''ulParmSize''fields refer to the [[00754.htm|CONTROL_PARM]]data structure. Values for ''ulCmd''include:

DDCMD_START Start a device.

DDCMD_STOP Stop a device and return current position.

DDCMD_PAUSE Pause a device and return current position.

DDCMD_RESUME Resume a paused device

DDCMD_ENABLE_EVENT Enable event detection.

DDCMD_DISABLE_EVENT Disable event detection in the device driver.

DDCMD_PAUSE_TIME Pause time but do not pause stream.

DDCMD_RESUME_TIME Resume time.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_REQUEST Device driver does not support events. (Returned when ''ulCmd''of [[00759.htm|DDCMDCONTROL]]is set to DDCMD_ENABLE_EVENT.)

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_SEQUENCE Invalid device control command.

ERROR_INSUFF_BUFFER The device driver does not have buffers to perform the requested action.

ERROR_STREAM_NOT_STARTED The stream cannot perform the requested action unless the stream has been started.

ERROR_TOO_MANY_EVENTS The stream handler attempted to enable too many events.

FAILURE Device-driver-specific error return code.





=== DDCMD_CONTROL Parameter - pParmIn ===

'''pParmIn'''([[00759.htm|PDDCMDCONTROL]]) A pointer to a [[00759.htm|DDCMDCONTROL]]data structure. The ''pParm''and ''ulParmSize''fields refer to the [[00754.htm|CONTROL_PARM]]data structure. Values for ''ulCmd''include:

DDCMD_START Start a device.

DDCMD_STOP Stop a device and return current position.

DDCMD_PAUSE Pause a device and return current position.

DDCMD_RESUME Resume a paused device

DDCMD_ENABLE_EVENT Enable event detection.

DDCMD_DISABLE_EVENT Disable event detection in the device driver.

DDCMD_PAUSE_TIME Pause time but do not pause stream.

DDCMD_RESUME_TIME Resume time.





=== DDCMD_CONTROL Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_REQUEST Device driver does not support events. (Returned when ''ulCmd''of [[00759.htm|DDCMDCONTROL]]is set to DDCMD_ENABLE_EVENT.)

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_SEQUENCE Invalid device control command.

ERROR_INSUFF_BUFFER The device driver does not have buffers to perform the requested action.

ERROR_STREAM_NOT_STARTED The stream cannot perform the requested action unless the stream has been started.

ERROR_TOO_MANY_EVENTS The stream handler attempted to enable too many events.

FAILURE Device-driver-specific error return code.





=== DDCMD_CONTROL - Syntax ===

This message performs a device-specific command.



'''pParmIn'''([[00759.htm|PDDCMDCONTROL]]) A pointer to a [[00759.htm|DDCMDCONTROL]]data structure. The ''pParm''and ''ulParmSize''fields refer to the [[00754.htm|CONTROL_PARM]]data structure. Values for ''ulCmd''include:

DDCMD_START Start a device.

DDCMD_STOP Stop a device and return current position.

DDCMD_PAUSE Pause a device and return current position.

DDCMD_RESUME Resume a paused device

DDCMD_ENABLE_EVENT Enable event detection.

DDCMD_DISABLE_EVENT Disable event detection in the device driver.

DDCMD_PAUSE_TIME Pause time but do not pause stream.

DDCMD_RESUME_TIME Resume time.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_REQUEST Device driver does not support events. (Returned when ''ulCmd''of [[00759.htm|DDCMDCONTROL]]is set to DDCMD_ENABLE_EVENT.)

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_SEQUENCE Invalid device control command.

ERROR_INSUFF_BUFFER The device driver does not have buffers to perform the requested action.

ERROR_STREAM_NOT_STARTED The stream cannot perform the requested action unless the stream has been started.

ERROR_TOO_MANY_EVENTS The stream handler attempted to enable too many events.

FAILURE Device-driver-specific error return code.





=== DDCMD_CONTROL - Remarks ===

The stream handler uses this command to control the actions of the physical device driver.





=== DDCMD_CONTROL - Example Code ===

The following code illustrates the stream handler requesting the PDD to stop its current task, for example, the PDD stops playing audio.

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG         ulRC;                      /* Error return code      */
  HSTREAM       hstream;                   /* Stream handle          */
  DDCMDCONTROL  ddcmdpb;                   /* Parameter block        */
  PDDCMDFN      pddcmdfn;                  /* Pointer to DDCMD entry
                                              point                  */
                            .
                            .
                            .
/*-------------------------------------------------------------------*/
/*  The stream handler directs the physical device driver to stop.   */
/*-------------------------------------------------------------------*/
  ddcmdpb.ulFunction = DDCMD_CONTROL;
  ddcmdpb.hstream = hstream;
  ddcmdpb.pParm = NULL;
  ddcmdpb.ulParmSize = NULL;
  ddcmdpb.ulCmd = DDCMD_STOP;

   if (ulRC = pddcmdfn (&amp;ddcmdpb))
     return (ulRC);    /* error!  */</pre>




=== DDCMD_CONTROL - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== DDCMD_DEREG_STREAM ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message removes a stream instance from a device driver. The stream handler directs the device driver to deregister the stream-destroy the stream and all associated data.



'''pParmIn'''([[00766.htm|PDDCMDDEREGISTER]]) A pointer to a [[00766.htm|DDCMDDEREGISTER]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

FAILURE Device-driver-specific error.





=== DDCMD_DEREG_STREAM Parameter - pParmIn ===

'''pParmIn'''([[00766.htm|PDDCMDDEREGISTER]]) A pointer to a [[00766.htm|DDCMDDEREGISTER]]data structure.





=== DDCMD_DEREG_STREAM Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

FAILURE Device-driver-specific error.





=== DDCMD_DEREG_STREAM - Syntax ===

This message removes a stream instance from a device driver. The stream handler directs the device driver to deregister the stream-destroy the stream and all associated data.



'''pParmIn'''([[00766.htm|PDDCMDDEREGISTER]]) A pointer to a [[00766.htm|DDCMDDEREGISTER]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

FAILURE Device-driver-specific error.





=== DDCMD_DEREG_STREAM - Remarks ===

�This message removes the communication link between the physical device driver and the stream handler for a particular stream instance. The only input is the stream handle, which indicates to the device driver which stream to destroy.

�After a deregister, the VSD (or device driver) no longer has access to any buffers, and the buffers will be returned to SSM by the stream handler. The VSD does not have to return the buffers; they are returned for the it. The VSD should not return from the destroy until it has stopped using all buffers.





=== DDCMD_DEREG_STREAM - Example Code ===

The following code illustrates the stream handler requesting the stream to be de-registered.

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG           ulRC;                    /* Error return code      */
  HSTREAM         hstream;                 /* Stream handle          */
  DDCMDDEREGISTER ddcmdpb;                 /* Parameter block        */
  PDDCMDFN        pddcmdfn;                /* Pointer to DDCMD entry */
                                           /* point                  */
                            .
                            .
                            .
/*-------------------------------------------------------------------*/
/*   The stream handler deregisters with the physical device driver. */
/*-------------------------------------------------------------------*/
  ddcmdpb.ulFunction = DDCMD_DEREG_STREAM;
  ddcmdpb.hstream = hstream;

  if (ulRC = pddcmdfn (&amp;ddcmdpb))
    return (ulRC);    /* error! */</pre>




=== DDCMD_DEREG_STREAM - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== DDCMD_READ ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message performs a read from the device into a buffer.



'''pParmIn'''([[00769.htm|PDDCMDREADWRITE]]) A pointer to a [[00769.htm|DDCMDREADWRITE]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_BLOCK Invalid address passed in parameter block.

FAILURE Device-driver-specific error return code.





=== DDCMD_READ Parameter - pParmIn ===

'''pParmIn'''([[00769.htm|PDDCMDREADWRITE]]) A pointer to a [[00769.htm|DDCMDREADWRITE]]data structure.





=== DDCMD_READ Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_BLOCK Invalid address passed in parameter block.

FAILURE Device-driver-specific error return code.





=== DDCMD_READ - Syntax ===

This message performs a read from the device into a buffer.



'''pParmIn'''([[00769.htm|PDDCMDREADWRITE]]) A pointer to a [[00769.htm|DDCMDREADWRITE]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_BLOCK Invalid address passed in parameter block.

FAILURE Device-driver-specific error return code.





=== DDCMD_READ - Remarks ===

This message is used by a stream handler to give an ''empty''buffer to the physical device driver. An example would be in an audio recording, where the physical device driver fills the buffer it gets from the stream handler . The ''pBuffer''parameter is a pointer to the buffer to be filled in by the physical device driver. This pointer is either a physical 0:32 pointer, 16: 16 far pointer or a global linear pointer. This is defined when the stream handler registers a stream with the device driver using [[00183.htm|DDCMD_REG_STREAM]].

Many devices cannot handle a 0 length buffer. If the driver receives a 0 length buffer, it should not reject the buffer. The driver should do nothing with the buffer and return it in the same order in which it was sent.





=== DDCMD_READ - Example Code ===

The following code illustrates the PDD ready to receive an empty buffer from the stream handler.

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG           ulRC;              /* Error return code            */
  HSTREAM         hstream;           /* Stream handle                */
  DDCMDREADWRITE  ddcmdpb;           /* Parameter block              */
  PDDCMDFN        pddcmdfn;          /* Pointer to DDCMD entry point */
  PVOID           pBuffer;           /* Pointer to buffer            */

                            .
                            .
                            .
/*-------------------------------------------------------------------*/
/*  Perform a read from the physical device driver.                  */
/*-------------------------------------------------------------------*/
  ddcmdpb.ulFunction = DDCMD_READ;
  ddcmdpb.hstream = hstream;
  ddcmdpb.pBuffer = pBuffer;
  ddcmdpb.ulBufferSize = 32768;

  if (ulRC = pddcmdfn (&amp;ddcmdpb))
    return (ulRC);    /* error!*/</pre>




=== DDCMD_READ - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== DDCMD_REG_STREAM ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message registers a stream instance with a device driver for the first time.



'''pParmIn'''([[00779.htm|PDDCMDREGISTER]]) A pointer to a [[00779.htm|DDCMDREGISTER]]data structure.

Values for ''ulStreamOperation''include:

�STREAM_OPERATION_CONSUME <br />�STREAM_OPERATION_PRODUCE

Values for ''ulAddressType''include:

�ADDRESS_TYPE_VIRTUAL <br />�ADDRESS_TYPE_PHYSICAL <br />�ADDRESS_TYPE_LINEAR

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_HNDLR_REGISTERED Stream had already been registered with the Sync/ Stream Manager.

ERROR_INVALID_SPCBKEY Invalid [[00991.htm|SPCBKEY]].

ERROR_INITIALIZATION An error occurred during device initialization.

ERROR_STREAM_CREATION An error occurred during the creation of this stream instance.

FAILURE Device-driver-specific error return code.





=== DDCMD_REG_STREAM Parameter - pParmIn ===

'''pParmIn'''([[00779.htm|PDDCMDREGISTER]]) A pointer to a [[00779.htm|DDCMDREGISTER]]data structure.

Values for ''ulStreamOperation''include:

�STREAM_OPERATION_CONSUME <br />�STREAM_OPERATION_PRODUCE

Values for ''ulAddressType''include:

�ADDRESS_TYPE_VIRTUAL <br />�ADDRESS_TYPE_PHYSICAL <br />�ADDRESS_TYPE_LINEAR





=== DDCMD_REG_STREAM Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_HNDLR_REGISTERED Stream had already been registered with the Sync/ Stream Manager.

ERROR_INVALID_SPCBKEY Invalid [[00991.htm|SPCBKEY]].

ERROR_INITIALIZATION An error occurred during device initialization.

ERROR_STREAM_CREATION An error occurred during the creation of this stream instance.

FAILURE Device-driver-specific error return code.





=== DDCMD_REG_STREAM - Syntax ===

This message registers a stream instance with a device driver for the first time.



'''pParmIn'''([[00779.htm|PDDCMDREGISTER]]) A pointer to a [[00779.htm|DDCMDREGISTER]]data structure.

Values for ''ulStreamOperation''include:

�STREAM_OPERATION_CONSUME <br />�STREAM_OPERATION_PRODUCE

Values for ''ulAddressType''include:

�ADDRESS_TYPE_VIRTUAL <br />�ADDRESS_TYPE_PHYSICAL <br />�ADDRESS_TYPE_LINEAR

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_HNDLR_REGISTERED Stream had already been registered with the Sync/ Stream Manager.

ERROR_INVALID_SPCBKEY Invalid [[00991.htm|SPCBKEY]].

ERROR_INITIALIZATION An error occurred during device initialization.

ERROR_STREAM_CREATION An error occurred during the creation of this stream instance.

FAILURE Device-driver-specific error return code.





=== DDCMD_REG_STREAM - Remarks ===

A stream handler must register its entry point with the device driver once for each stream instance. This message sets up the communication link between the stream handler and the physical device driver.





=== DDCMD_REG_STREAM - Example Code ===

The following code illustrates how to register a stream instance with a device driver.

<pre class="western"> #include        &quot;os2.h&quot;
 #include        &quot;os2me.h&quot;
 #include        &quot;shdd.h&quot;

   ULONG           ulRC;                    /* Error return code      */
   HSTREAM         hstream;                 /* Stream handle          */
   DDCMDREGISTER   ddcmdpb;                 /* Parameter block        */
   PDDCMDFN        pddcmdfn;                /* Pointer to DDCMD entry */
                                            /* point                  */
   ULONG           ulSysFileNum;            /* Global file handle     */
   PSHDFN          pshdfn;                  /* Pointer to SHD entry   */
                                            /* point                  */
   SPCBKEY         spcbkey;                 /* Stream protocol key    */

                             .
                             .
                             .
 /*-------------------------------------------------------------------*/
 /*  Register a stream instance with a physical device driver.        */
 /*-------------------------------------------------------------------*/
   ddcmdpb.ulFunction = DDCMD_REGISTER;
   ddcmdpb.hstream = hstream;
   ddcmdpb.ulSysFileNum = ulSysFileNum;
   ddcmdpb.pSHDEntryPoint = pshdfn;
   ddcmdpb.ulStreamOperation = STREAM_OPERATION_CONSUME;
   ddcmdpb.spcbkey = spcbkey;

  if (ulRC = pddcmdfn (&amp;ddcmdpb))
    return (ulRC);    /* error!*/</pre>




=== DDCMD_REG_STREAM - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== DDCMD_SETUP ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message performs device-specific stream instance setup.



'''pParmIn'''([[00793.htm|PDDCMDSETUP]]) A pointer to a [[00793.htm|DDCMDSETUP]]data structure. The ''pSetupParm''and ''ulSetupParmSize''fields refer to the [[00955.htm|SETUP_PARM]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_REQUEST Invalid setup request.

ERROR_STREAM_NOT_STOP The stream cannot perform the requested function unless the stream has been stopped.

FAILURE Device-driver-specific error return code.





=== DDCMD_SETUP Parameter - pParmIn ===

'''pParmIn'''([[00793.htm|PDDCMDSETUP]]) A pointer to a [[00793.htm|DDCMDSETUP]]data structure. The ''pSetupParm''and ''ulSetupParmSize''fields refer to the [[00955.htm|SETUP_PARM]]data structure.





=== DDCMD_SETUP Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_REQUEST Invalid setup request.

ERROR_STREAM_NOT_STOP The stream cannot perform the requested function unless the stream has been stopped.

FAILURE Device-driver-specific error return code.





=== DDCMD_SETUP - Syntax ===

This message performs device-specific stream instance setup.



'''pParmIn'''([[00793.htm|PDDCMDSETUP]]) A pointer to a [[00793.htm|DDCMDSETUP]]data structure. The ''pSetupParm''and ''ulSetupParmSize''fields refer to the [[00955.htm|SETUP_PARM]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_REQUEST Invalid setup request.

ERROR_STREAM_NOT_STOP The stream cannot perform the requested function unless the stream has been stopped.

FAILURE Device-driver-specific error return code.





=== DDCMD_SETUP - Remarks ===

This message indicates to the physical device driver that a specific stream instance will become the active stream instance. The ''pSetupParm''field is used for device-specific information. Typically, it is used to pass the current stream time from the stream handler to the PDD because a seek might have been requested on the stream prior to the stream start; thus, the PDD should adjust its time to this new reference time. Time is passed as a pointer to the time in milliseconds.





=== DDCMD_SETUP - Example Code ===

The following code illustrates how to perform device-specific stream instance setup.

<pre class="western"> #include        &quot;os2.h&quot;
 #include        &quot;os2me.h&quot;
 #include        &quot;shdd.h&quot;

   ULONG           ulRC;                    /* Error return code     */
   HSTREAM         hstream;                 /* Stream handle         */
   DDCMDSETUP      ddcmdpb;                 /* Parameter block       */
   PDDCMDFN        pddcmdfn;                /* Pointer to DDCMD entry*/
                                            /* point                 */
   ULONG           ulStreamTime             /* Stream time           */
   PVOID           pBuffer;                 /* Pointer to buffer     */

                             .
                             .
                             .
 /*------------------------------------------------------------------*/
 /*Activate a stream instance in a physical device driver (Switch    */
 /*                                                         context) */
 /*------------------------------------------------------------------*/
   ddcmdpb.ulFunction = DDCMD_SETUP;
   ddcmdpb.hstream = hstream;
   ddcmdpb.pSetupParm = &amp;ulStreamTime;    /* Setting stream time */
   ddcmdpbp.ulSetupParmSize = sizeof(ulStreamTime);

   if (ulRC = pddcmdfn (&amp;ddcmdpb))
     return (ulRC);    /* error!*/</pre>




=== DDCMD_SETUP - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== DDCMD_STATUS ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message requests status from the device.



'''pParmIn'''([[00798.htm|PDDCMDSTATUS]]) A pointer to a [[00798.htm|DDCMDSTATUS]]data structure. The ''pStatus''and ''ulStatusSize''fields refer to the [[00995.htm|STATUS_PARM]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

FAILURE Device-driver-specific error return code.





=== DDCMD_STATUS Parameter - pParmIn ===

'''pParmIn'''([[00798.htm|PDDCMDSTATUS]]) A pointer to a [[00798.htm|DDCMDSTATUS]]data structure. The ''pStatus''and ''ulStatusSize''fields refer to the [[00995.htm|STATUS_PARM]]data structure.





=== DDCMD_STATUS Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

FAILURE Device-driver-specific error return code.





=== DDCMD_STATUS - Syntax ===

This message requests status from the device.



'''pParmIn'''([[00798.htm|PDDCMDSTATUS]]) A pointer to a [[00798.htm|DDCMDSTATUS]]data structure. The ''pStatus''and ''ulStatusSize''fields refer to the [[00995.htm|STATUS_PARM]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

FAILURE Device-driver-specific error return code.





=== DDCMD_STATUS - Remarks ===

This message queries the status of physical device driver. This message might not be supported by all physical device drivers. It is commonly used by the stream handler to request the current stream time from the physical device driver.





=== DDCMD_STATUS - Example Code ===

The following code illustrates how to request status from the device.

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG           ulRC;                     /* Error return code      */
  HSTREAM         hstream;                  /* Stream handle          */
  DDCMDSTATUS     ddcmdpb;                  /* Parameter block        */
  PDDCMDFN        pddcmdfn;                 /* Pointer to DDCMD entry */
                                            /* point                  */
                            .
                            .
                            .
/*--------------------------------------------------------------------*/
/*  Get the current stream time from the physical device driver.      */
/*--------------------------------------------------------------------*/
  ddcmdpb.ulFunction = DDCMD_STATUS;
  ddcmdpb.hstream = hstream;
  ddcmdpb.pStatus =NULL;                    /* Return stream time*/
  ddcmdpb.ulStatusSize = 0;


  if (ulRC = pddcmdfn (&amp;ddcmdpb))
    return (ulRC);    /* error!*/
</pre>




=== DDCMD_STATUS - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== DDCMD_WRITE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message performs a write from the buffer to the device.



'''pParmIn'''([[00769.htm|PDDCMDREADWRITE]]) A pointer to a [[00769.htm|DDCMDREADWRITE]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_BLOCK Invalid address passed in parameter block.

FAILURE Device-driver-specific error return code.





=== DDCMD_WRITE Parameter - pParmIn ===

'''pParmIn'''([[00769.htm|PDDCMDREADWRITE]]) A pointer to a [[00769.htm|DDCMDREADWRITE]]data structure.





=== DDCMD_WRITE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_BLOCK Invalid address passed in parameter block.

FAILURE Device-driver-specific error return code.





=== DDCMD_WRITE - Syntax ===

This message performs a write from the buffer to the device.



'''pParmIn'''([[00769.htm|PDDCMDREADWRITE]]) A pointer to a [[00769.htm|DDCMDREADWRITE]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_BLOCK Invalid address passed in parameter block.

FAILURE Device-driver-specific error return code.





=== DDCMD_WRITE - Remarks ===

This message is used by a stream handler to give a full buffer to the physical device driver. An example would be the case of audio playback, where the stream handler passes a buffer with data to the physical device driver.

The ''pBuffer''parameter is a pointer to the data buffer. Note that this pointer is either a physical 0:32 pointer, 16:16 far pointer, or a global linear pointer. The pointer type is defined when the stream registers a stream with the device driver ([[00183.htm|DDCMD_REG_STREAM]]).

Many devices cannot handle a 0 length buffer. If the driver receives a 0 length buffer, it should not reject the buffer. The driver should do nothing with the buffer and return it in the same order in which it was sent.





=== DDCMD_WRITE - Example Code ===

The following code illustrates how to perform a write to the physical device driver.

<pre class="western"> #include        &quot;os2.h&quot;
 #include        &quot;os2me.h&quot;
 #include        &quot;shdd.h&quot;

   ULONG           ulRC;                     /* Error return code      */
   HSTREAM         hstream;                  /* Stream handle          */
   DDCMDREADWRITE  ddcmdpb;                  /* Parameter block        */
   PDDCMDFN        pddcmdfn;                 /* Pointer to DDCMD entry */
                                             /* point                  */
   PVOID           pBuffer;                  /* Pointer to buffer      */

                             .
                             .
                             .
 /*--------------------------------------------------------------------*/
 /*  Perform a write to the physical device driver.                    */
 /*--------------------------------------------------------------------*/
   ddcmdpb.ulFunction = DDCMD_WRITE;
   ddcmdpb.hstream = hstream;
   ddcmdpb.pBuffer = pBuffer;
   ddcmdpb.ulBufferSize = 32768;

   if (ulRC = pddcmdfn (&amp;ddcmdpb))
     return (ulRC);    /* error! */</pre>




=== DDCMD_WRITE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== SHD Messages ===

The stream handler device (SHD) messages are provided by a stream handler through a single entry point, [[00212.htm|SHDEntryPoint]], to a physical device driver. For this interface, all pointers are 16:16 pointers; this enables the current 16-bit device-driver model to be used for stream handlers. There are two SHD messages. The message number must be used in the ''ulFunction''field, of the parameter structure passed in the call, to indicate which message is being requested by the stream handler.

The following table lists the SHD messages:

<pre class="western">/-----------------------------------------------------------------\
|Message |Message             |Description                        |
|Number  |                    |                                   |
|--------+--------------------+-----------------------------------|
|1L      |SHD_REPORT_EVENT    |Reports an event to the stream     |
|        |                    |handler.                           |
|--------+--------------------+-----------------------------------|
|0L      |SHD_REPORT_INT      |Reports an interrupt from a device.|
\-----------------------------------------------------------------/</pre>




=== SHDEntryPoint ===


-----

Select an item:

<pre class="western">Syntax
Parameters 
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler.

<pre class="western">#include &lt;os2me.h&gt;

PSHD_COMMON    pCommon;  /*  Pointer to SHD_COMMON. */
ULONG          rc;       /*  Return codes. */

rc = SHDEntryPoint(pCommon);</pre>




=== SHDEntryPoint - Syntax ===

Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler.

<pre class="western">#include &lt;os2me.h&gt;

PSHD_COMMON    pCommon;  /*  Pointer to SHD_COMMON. */
ULONG          rc;       /*  Return codes. */

rc = SHDEntryPoint(pCommon);</pre>




=== SHDEntryPoint Parameter - pCommon ===

'''pCommon'''([[00958.htm|PSHD_COMMON]]) - input Pointer to [[00958.htm|SHD_COMMON]].





=== SHDEntryPoint Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) - returns Return codes indicating success or the type of failure :

NO_ERROR Successful.

ERROR_INVALID_FUNCTION Invalid function requested.

FAILURE An SHD message-specific error return code.





=== SHDEntryPoint - Parameters ===

'''pCommon'''([[00958.htm|PSHD_COMMON]]) - input Pointer to [[00958.htm|SHD_COMMON]].

'''rc'''([[00998.htm|ULONG]]) - returns Return codes indicating success or the type of failure :

NO_ERROR Successful.

ERROR_INVALID_FUNCTION Invalid function requested.

FAILURE An SHD message-specific error return code.





=== SHDEntryPoint - Remarks ===

Device driver stream handlers receive commands from PDDs to report events and interrupts. These Stream Handler Device (SHD) helper commands are provided through the SHDEntryPoint. This entry point is specifically used for the PDD to call back to the stream handler. For example, the PDD can send an [[00227.htm|SHD_REPORT_INT]]command to the stream handler to report status, indicate that a buffer is full, or specify that an additional buffer is required.





=== SHDEntryPoint - Example Code ===

The following code illustrates how to access this entry point, which is used for the PDD to communicate back to the stream handler.

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG           ulRC;                   /* Error return code          */
  HSTREAM         hstream;                /* Stream handle              */
  HEVENT          hevent;                 /* Event handle               */
  SHD_REPORTEVENT shdpb;                  /* Parameter block            */
  PSHDFN          pshdfn;                 /* Pointer to SHD entry point */
  ULONG           ulStreamTime;           /* Stream time                */

                            .
                            .
                            .
/*----------------------------------------------------------------------*/
/*  Report a cue point to the stream handler for a stream instance.     */
/*----------------------------------------------------------------------*/
  shdpb.ulFunction = SHD_REPORT_EVENT;
  shdpb.hstream = hstream;
  shdpb.hevent = hevent;
  shdpb.ulStreamTime = ulStreamTime;

  if (ulRC = pshdfn (&amp;shdpb))
    return (ulRC);    /* error! */</pre>




=== SHDEntryPoint - Topics ===

Select an item:

<pre class="western">Syntax
Parameters 
Returns 
Remarks 
Example Code 
Glossary </pre>




=== SHD_REPORT_EVENT ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message reports an event to the stream handler.



'''pParmIn'''([[00961.htm|PSHD_REPORTEVENT]]) A pointer to an [[00961.htm|SHD_REPORTEVENT]]data structure.

'''rc'''([[00998.htm|ULONG]]) Return codes indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_EVENT Invalid event handle.

FAILURE Stream-handler-specific error return code.





=== SHD_REPORT_EVENT Parameter - pParmIn ===

'''pParmIn'''([[00961.htm|PSHD_REPORTEVENT]]) A pointer to an [[00961.htm|SHD_REPORTEVENT]]data structure.





=== SHD_REPORT_EVENT Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Return codes indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_EVENT Invalid event handle.

FAILURE Stream-handler-specific error return code.





=== SHD_REPORT_EVENT - Syntax ===

This message reports an event to the stream handler.



'''pParmIn'''([[00961.htm|PSHD_REPORTEVENT]]) A pointer to an [[00961.htm|SHD_REPORTEVENT]]data structure.

'''rc'''([[00998.htm|ULONG]]) Return codes indicating success or the type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_INVALID_EVENT Invalid event handle.

FAILURE Stream-handler-specific error return code.





=== SHD_REPORT_EVENT - Remarks ===
This message is a mechanism for the physical device driver to report its own event (cue point) detection. The stream handler will call the PDD with an event via [[00162.htm|DDCMD_CONTROL]](DDCMD_ENABLE_EVENT) and the PDD will monitor the stream time for this event (if the PDD supports event detection). When the event is detected, the PDD will call back the stream handler and report this event via this message. The handle to the event and stream time must be set.





=== SHD_REPORT_EVENT - Example Code ===

The following code illustrates how to report an event to the stream handler .

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG           ulRC;                   /* Error return code          */
  HSTREAM         hstream;                /* Stream handle              */
  HEVENT          hevent;                 /* Event handle               */
  SHD_REPORTEVENT shdpb;                  /* Parameter block            */
  PSHDFN          pshdfn;                 /* Pointer to SHD entry point */
  ULONG           ulStreamTime;           /* Stream time                */

                            .
                            .
                            .
/*----------------------------------------------------------------------*/
/*  Report a cue point to the stream handler for a stream instance.     */
/*----------------------------------------------------------------------*/
  shdpb.ulFunction = SHD_REPORT_EVENT;
  shdpb.hstream = hstream;
  shdpb.hevent = hevent;
  shdpb.ulStreamTime = ulStreamTime;

  if (ulRC = pshdfn (&amp;shdpb))
    return (ulRC);    /* error! */</pre>




=== SHD_REPORT_EVENT - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== SHD_REPORT_INT ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This message is used by the physical device driver to report interrupts from a device and indicate that a new buffer is needed for consumption.



'''pParmIn'''([[00966.htm|PSHD_REPORTINT]]) A pointer to a [[00966.htm|SHD_REPORTINT]]data structure.

'''rc'''([[00998.htm|ULONG]]) Return codes indicating success or type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_DEVICE_UNDERRUN There was a device data underrun.

ERROR_DEVICE_OVERRUN There was a device data overrun.

FAILURE Stream-handler-specific error return code.





=== SHD_REPORT_INT Parameter - pParmIn ===

'''pParmIn'''([[00966.htm|PSHD_REPORTINT]]) A pointer to a [[00966.htm|SHD_REPORTINT]]data structure.





=== SHD_REPORT_INT Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Return codes indicating success or type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_DEVICE_UNDERRUN There was a device data underrun.

ERROR_DEVICE_OVERRUN There was a device data overrun.

FAILURE Stream-handler-specific error return code.





=== SHD_REPORT_INT - Syntax ===

This message is used by the physical device driver to report interrupts from a device and indicate that a new buffer is needed for consumption.



'''pParmIn'''([[00966.htm|PSHD_REPORTINT]]) A pointer to a [[00966.htm|SHD_REPORTINT]]data structure.

'''rc'''([[00998.htm|ULONG]]) Return codes indicating success or type of failure:

NO_ERROR Success.

ERROR_INVALID_FUNCTION Illegal function requested.

ERROR_INVALID_STREAM Invalid stream handle.

ERROR_DEVICE_UNDERRUN There was a device data underrun.

ERROR_DEVICE_OVERRUN There was a device data overrun.

FAILURE Stream-handler-specific error return code.





=== SHD_REPORT_INT - Remarks ===

This message is a mechanism for the physical device driver to return status , indicate that the buffer has been consumed, or indicate that a new buffer is needed.

When status is returned, you will know whether the playback or record was successful or if there was an error condition. Error conditions for playback are known as ''underruns'', which means the device is not getting data fast enough. Error conditions for records are called ''overruns'', which means the device is generating data faster than empty buffers become available. This might result in a data loss situation. For example, the device is constantly bringing in data from the analog ports of the adapter and converting it to digital data. If the device does not have any empty buffers to store the digital data, the data is lost.

If you report an underrun under Warp and want the stream handler to pause the device, you should report the ERROR_DEVICE_UNDERRUN as well as the SHD_ WRITE_COMPLETE flags.

The VSD must return buffers in the order they were sent and should not hold on to any buffers. Failure to return buffers could result in application hangs.





=== SHD_REPORT_INT - Example Code ===

The following code illustrates how to report an interrupt from a device.

<pre class="western">#include        &quot;os2.h&quot;
#include        &quot;os2me.h&quot;
#include        &quot;shdd.h&quot;

  ULONG           ulRC;                   /* Error return code          */
  HSTREAM         hstream;                /* Stream handle              */
  SHD_REPORTINT   shdpb;                  /* Parameter block            */
  PSHDFN          pshdfn;                 /* Pointer to SHD entry point */
  PVOID           pBuffer;                /* Pointer to buffer          */
  ULONG           ulStreamTime;           /* Stream time in millisecs   */

                            .
                            .
                            .
/*----------------------------------------------------------------------*/
/*  Report a read has completed.                                        */
/*----------------------------------------------------------------------*/
  shdpb.ulFunction = SHD_REPORT_INT;
  shdpb.hstream = hstream;
  shdpb.pBuffer = pBuffer;
  shdpb.ulFlag = SHD_READ_COMPLETE;
  shdpb.ulStatus = LengthRecordedBuffer;
  shdpb.ulStreamTime = ulStreamTime;

  if (ulRC = pshdfn (&amp;shdpb))
    return (ulRC);    /* error! */</pre>




=== SHD_REPORT_INT - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== Vendor-Specific Driver Commands ===

The vendor-specific driver (VSD) commands enable communication between vendor-specific drivers (VSDs) and an application such as the user-level audio stream handler or amplifier mixer MCI driver. The interface to the VSD is DLL-based. First, a DosLoadModule function is issued for the VSD's DLL. The DosLoadModule function returns a handle for the VSD. Next, using the VSD handle, DosQueryProcAddr is issued to receive the VSD entry point address. This must be done prior to issuing any VSD commands. Once the entry point address is received, calls to the VSD are made to [[00235.htm|VSDEntry]]entry point.





=== VSDEntry ===


-----

Select an item:

<pre class="western">Syntax
Parameters 
Returns 
Remarks 
Glossary </pre>

-----

This entry point enables communication between vendor-specific drivers ( VSDs) and an application such as the user-level audio stream handler or amplifier mixer. For audio VSDs, be sure to define INCL_AUDIO_VSD before including the VSDCMDS.H header file.

<pre class="western">#define INCL_AUDIO_VSD
#include &lt;vsdcmds.h&gt;
#include &lt;os2mixer.h&gt;

HVSD     hvsd;      /*  Handle to VSD instance. */
ULONG    ulFunc;    /*  Function code. */
ULONG    ulFlags;   /*  Flags for driver. */
PVOID    pRequest;  /*  Request parameter block value. */
ULONG    rc;        /*  Return codes. */

rc = VSDEntry(hvsd, ulFunc, ulFlags, pRequest);</pre>




=== VSDEntry - Syntax ===

This entry point enables communication between vendor-specific drivers ( VSDs) and an application such as the user-level audio stream handler or amplifier mixer. For audio VSDs, be sure to define INCL_AUDIO_VSD before including the VSDCMDS.H header file.

<pre class="western">#define INCL_AUDIO_VSD
#include &lt;vsdcmds.h&gt;
#include &lt;os2mixer.h&gt;

HVSD     hvsd;      /*  Handle to VSD instance. */
ULONG    ulFunc;    /*  Function code. */
ULONG    ulFlags;   /*  Flags for driver. */
PVOID    pRequest;  /*  Request parameter block value. */
ULONG    rc;        /*  Return codes. */

rc = VSDEntry(hvsd, ulFunc, ulFlags, pRequest);</pre>




=== VSDEntry Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) - input This parameter is the handle to the VSD instance.





=== VSDEntry Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) - input The VSD command to be issued. The following commands are supported for audio VSDs.

<pre class="western">/-------------------------------------------------------------\
|Command                       |Description                   |
|------------------------------+------------------------------|
|VSD_CLOSE                     |Closes the device. (Required) |
|------------------------------+------------------------------|
|VSD_DDCMD                     |Allows communication between  |
|                              |stream handlers and their     |
|                              |attached devices. (Required)  |
|------------------------------+------------------------------|
|VSD_ESCAPE                    |Sends a buffer to the device. |
|                              |(Optional)                    |
|------------------------------+------------------------------|
|VSD_GETDEVCAPS                |Retrieves the device          |
|                              |capabilities. (Required)      |
|------------------------------+------------------------------|
|VSD_OPEN                      |Opens an instance of the      |
|                              |device. (Required)            |
|------------------------------+------------------------------|
|VSD_QUERY                     |Queries the status of the     |
|                              |device. (Required)            |
|------------------------------+------------------------------|
|VSD_RESOURCE                  |Manages resources. (Required) |
|------------------------------+------------------------------|
|VSD_RESTORE                   |Restores device to a saved    |
|                              |state. (Required)             |
|------------------------------+------------------------------|
|VSD_SAVE                      |Saves the current state of the|
|                              |device instance. (Required)   |
|------------------------------+------------------------------|
|VSD_SET                       |Modifies settings of the      |
|                              |device. (Required)            |
|------------------------------+------------------------------|
|VSD_USER                      |Allows user-defined commands  |
|                              |to be passed into the VSD.    |
|                              |(Optional)                    |
\-------------------------------------------------------------/</pre>






=== VSDEntry Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) - input The ''ulFlags''parameter is used to further qualify the command specified in ''ulFunc''. In many cases it is used as a subcommand. For more information on ''ulFlags'', see the specific ''ulFunc''parameter.





=== VSDEntry Parameter - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) - input Specifies the pointer to the request packet. The caller of the VSD supplies all request buffers. See individual commands for more detailed information.





=== VSDEntry Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) - returns The return codes are listed for each command and will vary based on the command sent.

If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.





=== VSDEntry - Parameters ===

'''hvsd'''([[00810.htm|HVSD]]) - input This parameter is the handle to the VSD instance.

'''ulFunc'''([[00998.htm|ULONG]]) - input The VSD command to be issued. The following commands are supported for audio VSDs.

<pre class="western">/-------------------------------------------------------------\
|Command                       |Description                   |
|------------------------------+------------------------------|
|VSD_CLOSE                     |Closes the device. (Required) |
|------------------------------+------------------------------|
|VSD_DDCMD                     |Allows communication between  |
|                              |stream handlers and their     |
|                              |attached devices. (Required)  |
|------------------------------+------------------------------|
|VSD_ESCAPE                    |Sends a buffer to the device. |
|                              |(Optional)                    |
|------------------------------+------------------------------|
|VSD_GETDEVCAPS                |Retrieves the device          |
|                              |capabilities. (Required)      |
|------------------------------+------------------------------|
|VSD_OPEN                      |Opens an instance of the      |
|                              |device. (Required)            |
|------------------------------+------------------------------|
|VSD_QUERY                     |Queries the status of the     |
|                              |device. (Required)            |
|------------------------------+------------------------------|
|VSD_RESOURCE                  |Manages resources. (Required) |
|------------------------------+------------------------------|
|VSD_RESTORE                   |Restores device to a saved    |
|                              |state. (Required)             |
|------------------------------+------------------------------|
|VSD_SAVE                      |Saves the current state of the|
|                              |device instance. (Required)   |
|------------------------------+------------------------------|
|VSD_SET                       |Modifies settings of the      |
|                              |device. (Required)            |
|------------------------------+------------------------------|
|VSD_USER                      |Allows user-defined commands  |
|                              |to be passed into the VSD.    |
|                              |(Optional)                    |
\-------------------------------------------------------------/</pre>


'''ulFlags'''([[00998.htm|ULONG]]) - input The ''ulFlags''parameter is used to further qualify the command specified in ''ulFunc''. In many cases it is used as a subcommand. For more information on ''ulFlags'', see the specific ''ulFunc''parameter.

'''pRequest'''([[01203.htm|PVOID]]) - input Specifies the pointer to the request packet. The caller of the VSD supplies all request buffers. See individual commands for more detailed information.

'''rc'''([[00998.htm|ULONG]]) - returns The return codes are listed for each command and will vary based on the command sent.

If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.





=== VSDEntry - Remarks ===

If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.





=== VSDEntry - Topics ===

Select an item:

<pre class="western">Syntax
Parameters 
Returns 
Remarks 
Glossary </pre>




=== VSD_CLOSE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to the VSD to be closed.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_CLOSE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01203.htm|PVOID]]) Not used for this command.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_CANNOT_CLOSE VSD is unable to close the device.

VSDERR_HARDWARE A hardware error occurred.





=== VSD_CLOSE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to the VSD to be closed.





=== VSD_CLOSE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_CLOSE.





=== VSD_CLOSE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_CLOSE Parameter - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) Not used for this command.





=== VSD_CLOSE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_CANNOT_CLOSE VSD is unable to close the device.

VSDERR_HARDWARE A hardware error occurred.





=== VSD_CLOSE - Syntax ===

This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to the VSD to be closed.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_CLOSE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01203.htm|PVOID]]) Not used for this command.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_CANNOT_CLOSE VSD is unable to close the device.

VSDERR_HARDWARE A hardware error occurred.





=== VSD_CLOSE - Remarks ===

The ''hvsd''handle is no longer valid after this command is issued.





=== VSD_CLOSE - Example Code ===

The following code illustrates how to close a VSD.

<pre class="western">HVSD     hvsd;
    ULONG    rc;

    rc = pInstance -&gt;pfnAUDIOIF(  hvsd,
                                  VSD_CLOSE,
                                  0,
                                  0 );
    return (rc);</pre>




=== VSD_CLOSE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_DDCMD ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Glossary </pre>

-----

Stream handlers can communicate to their attached devices using the VSD_ DDCMD call. The DDCMD interface is the primary method of moving data to and from devices in OS/2 multimedia. See the ''OS/2 Multimedia Programming Reference''for more detailed information on stream handler command (SHC) messages.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_DDCMD.

'''ulFlags'''([[00998.htm|ULONG]]) The following flags (subcommands) are defined for this command:

DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. ''pRequest''is a pointer to the [[00759.htm|DDCMDCONTROL]]structure.

DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. ''pRequest''is a pointer to [[00766.htm|DDCMDDEREGISTER]]structure.

DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an ''empty''buffer to the VSD (for example, during a record operation). When the buffer has been filled, the VSD is responsible for communicating to the caller that the buffer has been filled. The VSD should pass a [[00946.htm|MSG_ REPORTINT]]structure to the ''pSHDEntryPoint''in [[00779.htm|DDCMDREGISTER]]to inform the caller.

''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.

DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. ''pRequest''is a pointer to [[00779.htm|DDCMDREGISTER]]structure.

DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest''is a pointer to [[00793.htm|DDCMDSETUP]]structure.

DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. ''pRequest''is a pointer to [[00798.htm|DDCMDSTATUS]]structure.

DDCMD_WRITE This VSD subcommand is used by a stream handler to give a ''full''buffer to the VSD (for example, during a playback operation). When the buffer has been consumed, the VSD is responsible for communicating to the caller that the buffer has been used. The VSD should pass a [[00946.htm|MSG_REPORTINT]]structure to the ''pSHDEntryPoint''in [[00779.htm|DDCMDREGISTER]]to inform the caller.

''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.

'''pRequest'''([[01203.htm|PVOID]]) The value of ''pRequest''varies according to the ''ulFlags''value. See each particular ''ulFlags''value for the definition of ''pRequest''.

'''rc'''([[00998.htm|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.





=== VSD_DDCMD Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_DDCMD Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_DDCMD.





=== VSD_DDCMD Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following flags (subcommands) are defined for this command:

DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. ''pRequest''is a pointer to the [[00759.htm|DDCMDCONTROL]]structure.

DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. ''pRequest''is a pointer to [[00766.htm|DDCMDDEREGISTER]]structure.

DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an ''empty''buffer to the VSD (for example, during a record operation). When the buffer has been filled, the VSD is responsible for communicating to the caller that the buffer has been filled. The VSD should pass a [[00946.htm|MSG_ REPORTINT]]structure to the ''pSHDEntryPoint''in [[00779.htm|DDCMDREGISTER]]to inform the caller.

''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.

DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. ''pRequest''is a pointer to [[00779.htm|DDCMDREGISTER]]structure.

DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest''is a pointer to [[00793.htm|DDCMDSETUP]]structure.

DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. ''pRequest''is a pointer to [[00798.htm|DDCMDSTATUS]]structure.

DDCMD_WRITE This VSD subcommand is used by a stream handler to give a ''full''buffer to the VSD (for example, during a playback operation). When the buffer has been consumed, the VSD is responsible for communicating to the caller that the buffer has been used. The VSD should pass a [[00946.htm|MSG_REPORTINT]]structure to the ''pSHDEntryPoint''in [[00779.htm|DDCMDREGISTER]]to inform the caller.

''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.





=== VSD_DDCMD Parameter - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) The value of ''pRequest''varies according to the ''ulFlags''value. See each particular ''ulFlags''value for the definition of ''pRequest''.





=== VSD_DDCMD Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.





=== VSD_DDCMD - Syntax ===

Stream handlers can communicate to their attached devices using the VSD_ DDCMD call. The DDCMD interface is the primary method of moving data to and from devices in OS/2 multimedia. See the ''OS/2 Multimedia Programming Reference''for more detailed information on stream handler command (SHC) messages.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_DDCMD.

'''ulFlags'''([[00998.htm|ULONG]]) The following flags (subcommands) are defined for this command:

DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. ''pRequest''is a pointer to the [[00759.htm|DDCMDCONTROL]]structure.

DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. ''pRequest''is a pointer to [[00766.htm|DDCMDDEREGISTER]]structure.

DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an ''empty''buffer to the VSD (for example, during a record operation). When the buffer has been filled, the VSD is responsible for communicating to the caller that the buffer has been filled. The VSD should pass a [[00946.htm|MSG_ REPORTINT]]structure to the ''pSHDEntryPoint''in [[00779.htm|DDCMDREGISTER]]to inform the caller.

''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.

DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. ''pRequest''is a pointer to [[00779.htm|DDCMDREGISTER]]structure.

DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest''is a pointer to [[00793.htm|DDCMDSETUP]]structure.

DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. ''pRequest''is a pointer to [[00798.htm|DDCMDSTATUS]]structure.

DDCMD_WRITE This VSD subcommand is used by a stream handler to give a ''full''buffer to the VSD (for example, during a playback operation). When the buffer has been consumed, the VSD is responsible for communicating to the caller that the buffer has been used. The VSD should pass a [[00946.htm|MSG_REPORTINT]]structure to the ''pSHDEntryPoint''in [[00779.htm|DDCMDREGISTER]]to inform the caller.

''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.

'''pRequest'''([[01203.htm|PVOID]]) The value of ''pRequest''varies according to the ''ulFlags''value. See each particular ''ulFlags''value for the definition of ''pRequest''.

'''rc'''([[00998.htm|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.





=== VSD_DDCMD - Remarks ===

A user-level 32-bit buffer pointer is available in the ''pProcessLin''field of the [[00769.htm|DDCMDREADWRITE]]. VSDs should use this pointer if they want to operate on the data while they are not in protect mode. The ''pBuffer''field of the [[00769.htm|DDCMDREADWRITE]]contains a pointer whose address type was specified by the VSD on DDCMD_REG_STREAM. When the application returns a buffer, it must return the buffer specified by ''pBuffer''and '''not'''by ''pProcessLin''





=== VSD_DDCMD - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Glossary </pre>




=== VSD_GETDEVCAPS ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This command queries the device capabilities. These values should be constants that describe the device and driver characteristics. In general, the flags indicate what set of commands are supported. VSD_GETDEVCAPS is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_GETDEVCAPS.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01169.htm|PVSD_GETDEVCAPS_PARMS]]) Pointer to the [[01169.htm|VSD_GETDEVCAPS_PARMS]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_REQUEST_BUF_TOO_SMALL The ''ulLength''in the request packet is too small.

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_HARDWARE A hardware error occurred.





=== VSD_GETDEVCAPS Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_GETDEVCAPS Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_GETDEVCAPS.





=== VSD_GETDEVCAPS Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_GETDEVCAPS Parameter - pRequest ===

'''pRequest'''([[01169.htm|PVSD_GETDEVCAPS_PARMS]]) Pointer to the [[01169.htm|VSD_GETDEVCAPS_PARMS]]data structure.





=== VSD_GETDEVCAPS Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_REQUEST_BUF_TOO_SMALL The ''ulLength''in the request packet is too small.

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_HARDWARE A hardware error occurred.





=== VSD_GETDEVCAPS - Syntax ===

This command queries the device capabilities. These values should be constants that describe the device and driver characteristics. In general, the flags indicate what set of commands are supported. VSD_GETDEVCAPS is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_GETDEVCAPS.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01169.htm|PVSD_GETDEVCAPS_PARMS]]) Pointer to the [[01169.htm|VSD_GETDEVCAPS_PARMS]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_REQUEST_BUF_TOO_SMALL The ''ulLength''in the request packet is too small.

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_HARDWARE A hardware error occurred.





=== VSD_GETDEVCAPS - Remarks ===

This command requires the device to be opened. A device might have several types of device units, so this command must know which instance is involved . Once the device is opened, the device capabilities should be constant.

Each element in the ''bSupports[DC_MAX_DEVCAP]''array of the [[01169.htm|VSD_GETDEVCAPS_ PARMS]]structure is a boolean value that indicates if the capability is supported. TRUE indicates that it is supported. FALSE indicates that it is not supported.





=== VSD_GETDEVCAPS - Example Code ===

The following code illustrates how to determine device capabilities for a VSD.

<pre class="western">  HVSD                   hvsd;
  VSD_GETDEVCAPS_PARMS   vsdDevCaps;

  rc = pInstance-&gt;pfnAUDIOIF(  hvsd,
                               VSD_GETDEVCAPS
                               0,
                               (PVOID) &amp;vsdDevCaps );

  if (!rc)
     {
    /* If the VSD doesn't support volume  */

    if( !vsdDevCaps.bSupports[ DC_HASVOLUME] )
       {
       return ( rc );
       }</pre>




=== VSD_GETDEVCAPS - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_ESCAPE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Glossary </pre>

-----

This optional command sends a buffer to the driver.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_ESCAPE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01165.htm|PVSD_ESCAPE_PARMS]]) A pointer to the [[01165.htm|VSD_ESCAPE_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_ESCAPE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_ESCAPE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_ESCAPE.





=== VSD_ESCAPE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_ESCAPE Parameter - pRequest ===

'''pRequest'''([[01165.htm|PVSD_ESCAPE_PARMS]]) A pointer to the [[01165.htm|VSD_ESCAPE_PARMS]]structure.





=== VSD_ESCAPE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_ESCAPE - Syntax ===

This optional command sends a buffer to the driver.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_ESCAPE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01165.htm|PVSD_ESCAPE_PARMS]]) A pointer to the [[01165.htm|VSD_ESCAPE_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_ESCAPE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Glossary </pre>




=== VSD_INSERTSETTINGSPAGE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Glossary </pre>

-----

This command enables a VSD to insert device-specific settings pages into the system configuration application.



'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD instance.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_INSERTSETTINGSPAGE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[00915.htm|PMCI_DEVICESETTINGS_PARMS]]) Pointer to the [[00915.htm|MCI_DEVICESETTINGS_ PARMS]]data structure.

'''hwndRC'''([[00811.htm|HWND]]) The return code contains the handle to a settings page or zero if no page is inserted.





=== VSD_INSERTSETTINGSPAGE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD instance.





=== VSD_INSERTSETTINGSPAGE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_INSERTSETTINGSPAGE.





=== VSD_INSERTSETTINGSPAGE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_INSERTSETTINGSPAGE Parameter - pRequest ===

'''pRequest'''([[00915.htm|PMCI_DEVICESETTINGS_PARMS]]) Pointer to the [[00915.htm|MCI_DEVICESETTINGS_ PARMS]]data structure.





=== VSD_INSERTSETTINGSPAGE Return Value - hwndRC ===

'''hwndRC'''([[00811.htm|HWND]]) The return code contains the handle to a settings page or zero if no page is inserted.





=== VSD_INSERTSETTINGSPAGE - Syntax ===

This command enables a VSD to insert device-specific settings pages into the system configuration application.



'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD instance.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_INSERTSETTINGSPAGE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[00915.htm|PMCI_DEVICESETTINGS_PARMS]]) Pointer to the [[00915.htm|MCI_DEVICESETTINGS_ PARMS]]data structure.

'''hwndRC'''([[00811.htm|HWND]]) The return code contains the handle to a settings page or zero if no page is inserted.





=== VSD_INSERTSETTINGSPAGE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Glossary </pre>




=== VSD_OPEN ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This command opens the device driver and returns a VSD handle or ([[00810.htm|HVSD]]). It should not allocate resources on the device (resource usage should be performed on the VSD restore).

VSD_OPEN is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Not used.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_OPEN.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01178.htm|PVSD_OPEN_PARMS]]) Pointer to the [[01178.htm|VSD_OPEN_PARMS]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_NO_DEVICE_DRIVER VSD is not connected to a device driver.

VSDERR_DEVICE_REJECTED Device driver rejected the request.

VSDERR_HARDWARE A hardware error occurred.

VSDERR_INVALID_BUFF ''pRequest''is not valid.





=== VSD_OPEN Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Not used.





=== VSD_OPEN Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_OPEN.





=== VSD_OPEN Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_OPEN Parameter - pRequest ===

'''pRequest'''([[01178.htm|PVSD_OPEN_PARMS]]) Pointer to the [[01178.htm|VSD_OPEN_PARMS]]data structure.





=== VSD_OPEN Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_NO_DEVICE_DRIVER VSD is not connected to a device driver.

VSDERR_DEVICE_REJECTED Device driver rejected the request.

VSDERR_HARDWARE A hardware error occurred.

VSDERR_INVALID_BUFF ''pRequest''is not valid.





=== VSD_OPEN - Syntax ===

This command opens the device driver and returns a VSD handle or ([[00810.htm|HVSD]]). It should not allocate resources on the device (resource usage should be performed on the VSD restore).

VSD_OPEN is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Not used.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_OPEN.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01178.htm|PVSD_OPEN_PARMS]]) Pointer to the [[01178.htm|VSD_OPEN_PARMS]]data structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_NO_DEVICE_DRIVER VSD is not connected to a device driver.

VSDERR_DEVICE_REJECTED Device driver rejected the request.

VSDERR_HARDWARE A hardware error occurred.

VSDERR_INVALID_BUFF ''pRequest''is not valid.





=== VSD_OPEN - Remarks ===

The installation name of the media control driver (MCD) is passed in so that the VSD can query device-specific parameters from the INI file.

For an audio VSD, the ''pDevInfo''pointer points to a [[01138.htm|VSD_AUDIOOPEN_PARMS]]structure. This structure contains enough information to initialize the audio device. The VSD is responsible for filling in the ''ulDataSubType''field of the [[01138.htm|VSD_AUDIOOPEN_PARMS]]structure with a valid data subtype.





=== VSD_OPEN - Example Code ===

The following code illustrates how to open an audio VSD.

<pre class="western"> VSD_OPEN_PARMS        vsdOpenParms;
 VSD_AUDIOOPEN_PARMS   vsdData;

 vsdData.ulLength = sizeof(VSD_AUDIOOPEN_PARMS);
 vsdData.ulFlags = 0;
 vsdData.ulSamplingRate       = pInstance-&gt;lSRate;
 vsdData.ulBitsPerSample      = pInstance-&gt;lBitsPerSRate;
 vsdData.ulChannels           = pInstance-&gt;sChannels;
 vsdData.ulDataType           = pInstance-&gt;sMode;
 vsdData.ulDeviceID           = pInstance-&gt;ulDeviceID;
 vsdData.ulOperation          = pInstance-&gt;ulOperation;
 vsdOpenParms.pDevInfo = (PVOID)&amp;vsdData;


     vsdOpenParms.ulLength = sizeof(VSD_OPEN_PARMS);
     memmove(&amp;vsdOpenParms.szPDDName,
             pInstance-&gt;szDeviceName,
             strlen(pInstance-&gt;szDeviceName));
       /* Open the audio VSD */
     rc = pInstance-&gt;pfnAUDIOIF(0,
                                VSD_OPEN,
                                0L
                                (PVOID)&amp;vsdOpenParms);
     if (!rc)
        }
        pInstance-&gt;hvsd = vsdOpenParms.hvsd;
        {</pre>




=== VSD_OPEN - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_QUERY ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Glossary </pre>

-----

This command allows an application to query the status of the VSD.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_QUERY.

'''ulFlags'''([[00998.htm|ULONG]]) The following flags can be used with VSD_QUERY:

VSD_QUERYAUDIOATTRIBUTES See [[00309.htm|VSD_QUERYAUDIOATTRIBUTES]].

VSD_QUERYCONNECTOR See [[00319.htm|VSD_QUERYCONNECTOR]].

VSD_QUERYDATATYPE See [[00328.htm|VSD_QUERYDATATYPE]].

VSD_QUERYMONITOR See [[00367.htm|VSD_QUERYMONITOR]].

VSD_QUERYVOLUME See [[00384.htm|VSD_QUERYVOLUME]].

VSD_QUERYMIXCONNECTIONS See [[00338.htm|VSD_QUERYMIXCONNECTIONS]].

VSD_QUERYMIXCONTROL See [[00348.htm|VSD_QUERYMIXCONTROL]].

VSD_QUERYMIXLINE See [[00358.htm|VSD_QUERYMIXLINE]].

'''pRequest'''([[01203.htm|PVOID]]) Pointer varies according to ''ulFlags''.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERY Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERY Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_QUERY.





=== VSD_QUERY Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following flags can be used with VSD_QUERY:

VSD_QUERYAUDIOATTRIBUTES See [[00309.htm|VSD_QUERYAUDIOATTRIBUTES]].

VSD_QUERYCONNECTOR See [[00319.htm|VSD_QUERYCONNECTOR]].

VSD_QUERYDATATYPE See [[00328.htm|VSD_QUERYDATATYPE]].

VSD_QUERYMONITOR See [[00367.htm|VSD_QUERYMONITOR]].

VSD_QUERYVOLUME See [[00384.htm|VSD_QUERYVOLUME]].

VSD_QUERYMIXCONNECTIONS See [[00338.htm|VSD_QUERYMIXCONNECTIONS]].

VSD_QUERYMIXCONTROL See [[00348.htm|VSD_QUERYMIXCONTROL]].

VSD_QUERYMIXLINE See [[00358.htm|VSD_QUERYMIXLINE]].





=== VSD_QUERY Return Value - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) Pointer varies according to ''ulFlags''.





=== VSD_QUERY Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERY - Syntax ===

This command allows an application to query the status of the VSD.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_QUERY.

'''ulFlags'''([[00998.htm|ULONG]]) The following flags can be used with VSD_QUERY:

VSD_QUERYAUDIOATTRIBUTES See [[00309.htm|VSD_QUERYAUDIOATTRIBUTES]].

VSD_QUERYCONNECTOR See [[00319.htm|VSD_QUERYCONNECTOR]].

VSD_QUERYDATATYPE See [[00328.htm|VSD_QUERYDATATYPE]].

VSD_QUERYMONITOR See [[00367.htm|VSD_QUERYMONITOR]].

VSD_QUERYVOLUME See [[00384.htm|VSD_QUERYVOLUME]].

VSD_QUERYMIXCONNECTIONS See [[00338.htm|VSD_QUERYMIXCONNECTIONS]].

VSD_QUERYMIXCONTROL See [[00348.htm|VSD_QUERYMIXCONTROL]].

VSD_QUERYMIXLINE See [[00358.htm|VSD_QUERYMIXLINE]].

'''pRequest'''([[01203.htm|PVOID]]) Pointer varies according to ''ulFlags''.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERY - Remarks ===

This command uses flags to indicate what information is queried.





=== VSD_QUERY - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Glossary </pre>




=== VSD_QUERYAUDIOATTRIBUTES ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the current audio settings and capabilities. A valid length must be placed in the ''ulLength''field of the [[01119.htm|VSD_AUDIOATTRIBUTES_PARMS]]structure and the audio setting (such as treble, bass, and so on) must be placed in the ''ulFlags''field of the [[01119.htm|VSD_ AUDIOATTRIBUTES_PARMS]]structure.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYAUDIOATTRIBUTES.

'''pRequest'''([[01119.htm|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[01119.htm|VSD_AUDIOATTRIBUTES_ PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYAUDIOATTRIBUTES Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYAUDIOATTRIBUTES Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYAUDIOATTRIBUTES Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYAUDIOATTRIBUTES.





=== VSD_QUERYAUDIOATTRIBUTES Parameter - pRequest ===

'''pRequest'''([[01119.htm|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[01119.htm|VSD_AUDIOATTRIBUTES_ PARMS]]structure.





=== VSD_QUERYAUDIOATTRIBUTES Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYAUDIOATTRIBUTES - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the current audio settings and capabilities. A valid length must be placed in the ''ulLength''field of the [[01119.htm|VSD_AUDIOATTRIBUTES_PARMS]]structure and the audio setting (such as treble, bass, and so on) must be placed in the ''ulFlags''field of the [[01119.htm|VSD_ AUDIOATTRIBUTES_PARMS]]structure.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYAUDIOATTRIBUTES.

'''pRequest'''([[01119.htm|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[01119.htm|VSD_AUDIOATTRIBUTES_ PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYAUDIOATTRIBUTES - Remarks ===

All values are returned in the ''ulValue''field and can range from 0 - 100.





=== VSD_QUERYAUDIOATTRIBUTES - Example Code ===

The following code illustrates how to query audio attribute information from the VSD.

<pre class="western">HVSD                        hvsd;
VSD_AUDIOATTRIBUTES_PARMS   vsdAttr;

    /* Prime the structure with necessary values */
vsdAttr.ulLength = sizeof (VSD_AUDIOATTRIBUTES_PARMS);
vsdAttr.ulFlags = VSD_BASS;

    /*---------------------------------------------
     * Ask the VSD to either set or query an audio
     * attribute.  The caller determines whether
     * to set or query via the command variable.
     *---------------------------------------------*/

     rc = pInstance-&gt;pfnAUDIOIF(hvsd,
                                VSD_QUERY,
                                VSD_QUERYAUDIOATTRIBUTES,
                                (PVOID)&amp;vsdAttr);

    /* If Bass value is too high then...*/
    if (!rc)
       {
       if (vsdAttr.ulValue &gt; 70)
       {
       }</pre>




=== VSD_QUERYAUDIOATTRIBUTES - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_QUERYCONNECTOR ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the state of the connector . (A connector can be a hardware or software connection on the device the VSD is controlling.) If the connector is enabled, the ''fEnabled''field of the [[01159.htm|VSD_CONNECTOR_PARMS]]structure will contain MCI_TRUE, otherwise it will contain MCI_FALSE. For further information regarding connectors, refer to the MCI connector command in the ''OS/2 Multimedia Programming Reference''. Valid connectors can be found in MCIOS2.H.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYCONNECTOR.

'''pRequest'''([[01159.htm|PVSD_CONNECTOR_PARMS]]) A pointer to the [[01159.htm|VSD_CONNECTOR_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_UNSUPPORTED_CONN_TYPE Connector type not supported.

VSDERR_INVALID_CONNECTOR_TYPE Invalid connector type.

VSDERR_INVALID_CONNECTOR_INDEX Invalid connector index.

VSDERR_CANNOT_MODIFY_CONNECTOR Cannot enable or disable this connector.

VSDERR_INVALID_CONNECTOR Invalid connector.

VSDERR_UNSUPPORTED_CONNECTOR Unsupported connector.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYCONNECTOR Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYCONNECTOR Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYCONNECTOR Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYCONNECTOR.





=== VSD_QUERYCONNECTOR Parameter - pRequest ===

'''pRequest'''([[01159.htm|PVSD_CONNECTOR_PARMS]]) A pointer to the [[01159.htm|VSD_CONNECTOR_PARMS]]structure.





=== VSD_QUERYCONNECTOR Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_UNSUPPORTED_CONN_TYPE Connector type not supported.

VSDERR_INVALID_CONNECTOR_TYPE Invalid connector type.

VSDERR_INVALID_CONNECTOR_INDEX Invalid connector index.

VSDERR_CANNOT_MODIFY_CONNECTOR Cannot enable or disable this connector.

VSDERR_INVALID_CONNECTOR Invalid connector.

VSDERR_UNSUPPORTED_CONNECTOR Unsupported connector.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYCONNECTOR - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the state of the connector . (A connector can be a hardware or software connection on the device the VSD is controlling.) If the connector is enabled, the ''fEnabled''field of the [[01159.htm|VSD_CONNECTOR_PARMS]]structure will contain MCI_TRUE, otherwise it will contain MCI_FALSE. For further information regarding connectors, refer to the MCI connector command in the ''OS/2 Multimedia Programming Reference''. Valid connectors can be found in MCIOS2.H.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYCONNECTOR.

'''pRequest'''([[01159.htm|PVSD_CONNECTOR_PARMS]]) A pointer to the [[01159.htm|VSD_CONNECTOR_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_UNSUPPORTED_CONN_TYPE Connector type not supported.

VSDERR_INVALID_CONNECTOR_TYPE Invalid connector type.

VSDERR_INVALID_CONNECTOR_INDEX Invalid connector index.

VSDERR_CANNOT_MODIFY_CONNECTOR Cannot enable or disable this connector.

VSDERR_INVALID_CONNECTOR Invalid connector.

VSDERR_UNSUPPORTED_CONNECTOR Unsupported connector.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYCONNECTOR - Example Code ===

The following code illustrates how to query the state of the connector.

<pre class="western">    HVSD                   hvsd;
    VSD_CONNECTOR_PARMS    vsdConn;

    vsdConn.ulConn_Type = pConnector-&gt;ulConnectorType;
    vsdConn.ulIndex = pConnector-&gt;ulConnectorIndex;

    lError = pInstance-&gt;pfnNewVSD(hvsd,
                                  VSD_QUERY,
                                  VSD_QUERYCONNECTOR,
                                  (PVOID)&amp;vsdConn);

    prConnector-&gt;ulReturn = vsdConn.fEnabled;</pre>




=== VSD_QUERYCONNECTOR - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_QUERYDATATYPE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries if a particular set of data types are supported. The ''ulSamplingRate'', ''ulBitsPerSample'', ''ulChannels'', and ''ulDataType''will be filled in on input. The ''ulDataSubType''is filled in by the VSD on output. If the current mode is not supported, the VSD should fill in the ''ulSamplingRate'', ''ulBitsPerSample'', and ''ulChannels''with the closest that it supports.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYDATATYPE.

'''pRequest'''([[01124.htm|PVSD_AUDIODATATYPE_PARMS]]) Pointer to the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYDATATYPE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYDATATYPE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYDATATYPE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYDATATYPE.





=== VSD_QUERYDATATYPE Parameter - pRequest ===

'''pRequest'''([[01124.htm|PVSD_AUDIODATATYPE_PARMS]]) Pointer to the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure.





=== VSD_QUERYDATATYPE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYDATATYPE - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries if a particular set of data types are supported. The ''ulSamplingRate'', ''ulBitsPerSample'', ''ulChannels'', and ''ulDataType''will be filled in on input. The ''ulDataSubType''is filled in by the VSD on output. If the current mode is not supported, the VSD should fill in the ''ulSamplingRate'', ''ulBitsPerSample'', and ''ulChannels''with the closest that it supports.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYDATATYPE.

'''pRequest'''([[01124.htm|PVSD_AUDIODATATYPE_PARMS]]) Pointer to the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_QUERYDATATYPE - Remarks ===

This command is typically sent by applications which need to determine if the VSD supports a particular datatype.





=== VSD_QUERYDATATYPE - Example Code ===

The following code illustrates the use of VSD_QUERYDATATYPE:

<pre class="western"> HVSD                       hvsd;
 VSD_AUDIODATATYPE_PARMS    AudioCaps;

   /*---------------------------------------
   * Tell the VSD that we want to enable a
   * connector.
   *---------------------------------------*/
   rc =  pInstance-&gt;pfnNewVSD( hvsd ,
                               VSD_QUERY,
                               VSD_QUERYDATATYPE,
                               (PVOID ) &amp;AudioCaps );

   if ( rc )
      {
        rc = MCIERR_INVALID_CONNECTION ;
      return (rc);
      }
   else
      {
      rc = MCIERR_SUCCESS;
      }

   return ( rc );

      } /* TestConnection */</pre>




=== VSD_QUERYDATATYPE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_QUERYMIXCONNECTIONS ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the output that a particular VSD line (or connector) is routed to. For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXCONNECTIONS.

'''pRequest'''([[00812.htm|PLINECONNECTIONS]]) A pointer to the [[00812.htm|LINECONNECTIONS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXCONNECTIONS Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYMIXCONNECTIONS Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYMIXCONNECTIONS Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXCONNECTIONS.





=== VSD_QUERYMIXCONNECTIONS Parameter - pRequest ===

'''pRequest'''([[00812.htm|PLINECONNECTIONS]]) A pointer to the [[00812.htm|LINECONNECTIONS]]structure.





=== VSD_QUERYMIXCONNECTIONS Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXCONNECTIONS - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the output that a particular VSD line (or connector) is routed to. For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXCONNECTIONS.

'''pRequest'''([[00812.htm|PLINECONNECTIONS]]) A pointer to the [[00812.htm|LINECONNECTIONS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXCONNECTIONS - Remarks ===

The ''ulConnections''field of the [[00812.htm|LINECONNECTIONS]]structure returns the particular output that a line is routed to. The ''ulLine''field of the [[00812.htm|LINECONNECTIONS]]structure must contain a valid line on input. For more information on the values for ''ulLine''and ''ulConnections'', see the [[00812.htm|LINECONNECTIONS]]structure.





=== VSD_QUERYMIXCONNECTIONS - Example Code ===

The following code illustrates how to query the output that a particular line is routed to.

<pre class="western">  HVSD              hvsd;
  LINECONNECTIONS   LineCon;

 /* Find out the setting for the synth. */

  LineCon.ulLine = SOURCE_SYNTHESIZER;

  LineCon.ulLength = sizeof(MIXERLINEINFO);
 /* Ask VSD for the capabilities of this line. */

  rc = pInstance-&gt;(hvsd,
                   VSD_QUERY,
                   VSD_QUERYMIXCONNECTIONS,
                   (PVOID)&amp;LineCon);

 /* Are we connected to the amp or record outputs... */

  if (LineCon.ulConnection &amp; (SINK_SPEAKERS))
     {
     pMixParms-&gt;ulReturn = MCI_OUTPUT_AMP;
     }
  else
     {
     pMixParms-&gt;ulReturn = MCI_OUTPUT_DIGITALAUDIO;
     }</pre>




=== VSD_QUERYMIXCONNECTIONS - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_QUERYMIXCONTROL ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the audio attributes for an audio VSD connector (for example, the treble setting on a microphone connector). For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXCONTROL.

'''pRequest'''([[00930.htm|PMIXERCONTROL]]) A pointer to the [[00930.htm|MIXERCONTROL]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXCONTROL Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYMIXCONTROL Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYMIXCONTROL Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXCONTROL.





=== VSD_QUERYMIXCONTROL Parameter - pRequest ===

'''pRequest'''([[00930.htm|PMIXERCONTROL]]) A pointer to the [[00930.htm|MIXERCONTROL]]structure.





=== VSD_QUERYMIXCONTROL Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXCONTROL - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the audio attributes for an audio VSD connector (for example, the treble setting on a microphone connector). For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXCONTROL.

'''pRequest'''([[00930.htm|PMIXERCONTROL]]) A pointer to the [[00930.htm|MIXERCONTROL]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXCONTROL - Remarks ===

The ''ulLine''field of the [[00930.htm|MIXERCONTROL]]structure must be filled in with one of the VSD sources/sinks in the low-order byte of the low word.

The ''ulControl''field of the [[00930.htm|MIXERCONTROL]]structure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting and the low-order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout.





=== VSD_QUERYMIXCONTROL - Example Code ===

The following code illustrates how to query the settings of audio attributes for a particular connector.

<pre class="western">  HVSD           hvsd;
  MIXERCONTROL   MixerControl;
  USHORT         usBass;

 /* Find out the setting for the synth. */

  MixerControl.ulLine = SOURCE_SYNTHESIZER;

 /* Ask VSD what is the current setting of the connector. */

  MixerControl.ulControl = MIX_BASS;
  rc = pInstance-&gt;(hvsd,
                   VSD_QUERY,
                   VSD_QUERYMIXCONTROL,
                   (PVOID)&amp;MixerControl);

     usBass = (MixControl.ulSetting)

     }</pre>




=== VSD_QUERYMIXCONTROL - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_QUERYMIXLINE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the audio attributes that are supported for the given VSD connector. For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_QUERY.

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXLINE.

'''pRequest'''([[00935.htm|PMIXERLINEINFO]]) A pointer to the [[00935.htm|MIXERLINEINFO]]structure. The ''ulSupport''field will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ''ulLine''field must be filled in by the caller.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXLINE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYMIXLINE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_QUERY.





=== VSD_QUERYMIXLINE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXLINE.





=== VSD_QUERYMIXLINE Parameter - pRequest ===

'''pRequest'''([[00935.htm|PMIXERLINEINFO]]) A pointer to the [[00935.htm|MIXERLINEINFO]]structure. The ''ulSupport''field will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ''ulLine''field must be filled in by the caller.





=== VSD_QUERYMIXLINE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXLINE - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the audio attributes that are supported for the given VSD connector. For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_QUERY.

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMIXLINE.

'''pRequest'''([[00935.htm|PMIXERLINEINFO]]) A pointer to the [[00935.htm|MIXERLINEINFO]]structure. The ''ulSupport''field will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ''ulLine''field must be filled in by the caller.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_QUERYMIXLINE - Example Code ===

The following code illustrates how to query the supported audio attributes from a mixer connector.

<pre class="western">HVSD               hvsd;
MIXERLINEINFO      mixerinfo;
  mixerinfo.ulLine = SYNTHESIZER_INPUT;
  mixerinfo.ulLength = sizeof(MIXERLINEINFO);
      rc = pInstance-&gt;pfnAUDIOIF( hsvd,
                                  VSD_QUERY,
                                  VSD_QUERYMIXLINE,
                                  (PVOID) &amp;mixerinfo);

   if(!rc)
      if(mixerinfo.ulSupport &amp; MIX_VOLUME)
          {
          /* process volume */
          }

        }  /* If no errors */</pre>




=== VSD_QUERYMIXLINE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_QUERYMONITOR ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the device to determine if audio monitoring is enabled. The VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD instance.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMONITOR.

'''pRequest'''([[00998.htm|PULONG]]) Output.

'''rc'''([[00998.htm|ULONG]]) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.





=== VSD_QUERYMONITOR Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD instance.





=== VSD_QUERYMONITOR Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYMONITOR Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMONITOR.





=== VSD_QUERYMONITOR Parameter - pRequest ===

'''pRequest'''([[00998.htm|PULONG]]) Output.





=== VSD_QUERYMONITOR Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.





=== VSD_QUERYMONITOR - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the device to determine if audio monitoring is enabled. The VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD instance.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYMONITOR.

'''pRequest'''([[00998.htm|PULONG]]) Output.

'''rc'''([[00998.htm|ULONG]]) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.





=== VSD_QUERYMONITOR - Example Code ===

The following code illustrates how to query the state of monitoring.

<pre class="western">rc = pInstance-&gt;pfnAUDIOIF((HVSD)pInstance-&gt;hvsd,
                           VSD_QUERY,
                           VSD_QUERYMONITOR,
                           (PVOID)&amp;pStat-&gt;ulReturn);</pre>




=== VSD_QUERYMONITOR - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_QUERYSTATUSLEVEL ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the status of the audio input level (percentage). This command is optional.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYSTATUSLEVEL.

'''pRequest'''([[00998.htm|PULONG]]) Current level of device.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_QUERYSTATUSLEVEL Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYSTATUSLEVEL Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYSTATUSLEVEL Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYSTATUSLEVEL.





=== VSD_QUERYSTATUSLEVEL Parameter - pRequest ===

'''pRequest'''([[00998.htm|PULONG]]) Current level of device.





=== VSD_QUERYSTATUSLEVEL Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_QUERYSTATUSLEVEL - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the status of the audio input level (percentage). This command is optional.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYSTATUSLEVEL.

'''pRequest'''([[00998.htm|PULONG]]) Current level of device.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_QUERYSTATUSLEVEL - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Glossary </pre>




=== VSD_QUERYVOLUME ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the volume level. The volume is returned as a percentage between 0% and 100%

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYVOLUME.

'''pRequest'''([[01194.htm|PVSD_VOLUME_PARMS]]) Pointer to the [[01194.htm|VSD_VOLUME_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful. field.





=== VSD_QUERYVOLUME Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_QUERYVOLUME Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].





=== VSD_QUERYVOLUME Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYVOLUME.





=== VSD_QUERYVOLUME Parameter - pRequest ===

'''pRequest'''([[01194.htm|PVSD_VOLUME_PARMS]]) Pointer to the [[01194.htm|VSD_VOLUME_PARMS]]structure.





=== VSD_QUERYVOLUME Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful. field.





=== VSD_QUERYVOLUME - Syntax ===

This subcommand of the [[00300.htm|VSD_QUERY]]command queries the volume level. The volume is returned as a percentage between 0% and 100%

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00300.htm|VSD_QUERY]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_QUERYVOLUME.

'''pRequest'''([[01194.htm|PVSD_VOLUME_PARMS]]) Pointer to the [[01194.htm|VSD_VOLUME_PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful. field.





=== VSD_QUERYVOLUME - Remarks ===

On return, the VSD will fill in the ''ulVolume''field of the [[01194.htm|VSD_VOLUME_PARMS]]structure.





=== VSD_QUERYVOLUME - Example Code ===

The following code illustrates how to query audio volume from the VSD.

<pre class="western">VSD_VOLUME_PARMS   vsdVol;
ULONG              ulVol;
   vsdVol.ulLength = sizeof(VSD_VOLUME_PARMS);
   vsdVol.ulFlags  = ulFlags;

 /*------------------------------------------
  *  Ask the VSD to query audio volume.
  *------------------------------------------*/

rc = pInstance-&gt;pfnAUDIOIF((HVSD)pInstance-&gt;hvsd,
                           VSD_QUERY,
                           VSD_QUERYVOLUME,
                           (PVOID)&amp;vsdVol);
ulVol = vsdvol.ulVolume;</pre>




=== VSD_QUERYVOLUME - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_RESOURCE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This command can be issued only when the device is opened and is used for resource management.

VSD_RESOURCE is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_RESOURCE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01187.htm|PVSD_RESOURCE_PARMS]]) Pointer to the [[01187.htm|VSD_RESOURCE_PARMS]]data structure.

The driver is responsible for filling in the ''ulResUnits''and ''ulClass''fields. The caller is responsible for filling in the ''ulDataType''field.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters is missing.





=== VSD_RESOURCE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_RESOURCE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_RESOURCE.





=== VSD_RESOURCE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_RESOURCE Parameter - pRequest ===

'''pRequest'''([[01187.htm|PVSD_RESOURCE_PARMS]]) Pointer to the [[01187.htm|VSD_RESOURCE_PARMS]]data structure.

The driver is responsible for filling in the ''ulResUnits''and ''ulClass''fields. The caller is responsible for filling in the ''ulDataType''field.





=== VSD_RESOURCE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters is missing.





=== VSD_RESOURCE - Syntax ===

This command can be issued only when the device is opened and is used for resource management.

VSD_RESOURCE is a required command and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_RESOURCE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01187.htm|PVSD_RESOURCE_PARMS]]) Pointer to the [[01187.htm|VSD_RESOURCE_PARMS]]data structure.

The driver is responsible for filling in the ''ulResUnits''and ''ulClass''fields. The caller is responsible for filling in the ''ulDataType''field.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS Command completed successfully.

VSDERR_MISSING_PARAMETER One or more parameters is missing.





=== VSD_RESOURCE - Remarks ===

When an audio device driver is installed in MMPM/2, the installation routines place the following three keywords in the MMPM2.INI file:

�RESOURCEUNITS=

�RESOURCECLASS=

�VALIDCOMBINATIONS=

Because MMPM/2 allows many applications to simultaneously open the audio card, it uses these keywords to determine which applications can simultaneously use the audio device. All of the numbers are arbitrary and are defined on a device-by-device basis. However, device driver writers should use the numbering scheme defined below:

The keyword '''RESOURCECLASSES'''indicates the different resource types available on the audio device. ''The first parameter is the number of classes and it is followed by a listing of classes. A vendor should provide a class for each data type that they support''. For instance, if the XYZ audio card can only play PCM files, it would only have one resource class - the PCM class. However, if the ABC audio card can play PCM, MIDI, and ADPCM, then it would have three classes. The VSD should fill in the ''ulClass''field with the class that is appropriate for this mode.

The keyword '''RESOURCEUNITS'''indicates the maximum number of instances that can be active on the card at any particular time. For example, if the XYZ card mentioned above had the ability to play three PCM files at the same time, the RESOURCEUNITS for this card would be three. In contrast, the ABC card can only play one PCM file and one MIDI file at any one time. Therefore, its resource units should be two. The VSD should fill in the ''ulResUnits''field with the correct number of resources for the current mode (typically, one).





=== VSD_RESOURCE - Example Code ===

The following code illustrates how to determine the number of resources consumed for a particular mode on an audio VSD.

<pre class="western"> HVSD   hvsd;
  rc = pInstance-&gt;pfnAUDIOIF( hvsd,
                              VSD_RESOURCE,
                              0L,
                              (PVOID)&amp;vsdResourceParms );

  pInstance-&gt;ulResourcesUsed = vsdResourceParms.ulResUnits;
  pInstance-&gt;ulClass = vsdResourceParms.ulClass;</pre>




=== VSD_RESOURCE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_RESTORE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This command restores the current state of the device. VSD_RESTORE is a required function and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_RESTORE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01203.htm|PVOID]]) Not used with this command.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command completed successfully.





=== VSD_RESTORE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_RESTORE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_RESTORE.





=== VSD_RESTORE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_RESTORE Parameter - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) Not used with this command.





=== VSD_RESTORE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command completed successfully.





=== VSD_RESTORE - Syntax ===

This command restores the current state of the device. VSD_RESTORE is a required function and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_RESTORE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01203.htm|PVOID]]) Not used with this command.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command completed successfully.





=== VSD_RESTORE - Remarks ===

MMPM/2 supports the concept of suspending and resuming the state of a device at any point in time. Unlike other environments, multiple applications can simultaneously have a device open and the Media Device Manager will cooperate with the VSD in order to manage the device. The VSD is responsible for saving and restoring the actual hardware device. For further information, see the ''OS/2 Multimedia Programming Reference''(MCI_ RESTORE).





=== VSD_RESTORE - Example Code ===

The following code illustrates how to activate an audio VSD using VSD_ RESTORE.

<pre class="western">   ULONG   rc;
   HVSD    hvsd;

       rc = pInstance-&gt;pfnAUDIOIF( hvsd,
                                   VSD_RESTORE,
                                   0L,
                                   0 );
       return(rc)</pre>




=== VSD_RESTORE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_SAVE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>

-----

This command saves the current state of the device. VSD_SAVE is a required function and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SAVE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01203.htm|PVOID]]) Not used with this command.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_SAVE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SAVE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SAVE.





=== VSD_SAVE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.





=== VSD_SAVE Parameter - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) Not used with this command.





=== VSD_SAVE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_SAVE - Syntax ===

This command saves the current state of the device. VSD_SAVE is a required function and must be implemented by all VSD writers.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SAVE.

'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.

'''pRequest'''([[01203.htm|PVOID]]) Not used with this command.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_SAVE - Remarks ===

MMPM/2 supports the concept of suspending and resuming the state of a device at any point in time. Unlike other environments, multiple applications can simultaneously have a device open and the Media Device Manager will cooperate with the VSD in order to manage the device. The VSD is responsible for saving and restoring the actual hardware device. For further information, see the ''OS/2 Multimedia Programming Reference''(MCIDRV_ SAVE).





=== VSD_SAVE - Example Code ===

The following code illustrates how to deactivate an audio VSD using VSD_ SAVE.

<pre class="western">   ULONG    rc;
   HVSD    hvsd;

     rc = pInstance-&gt;pfnAUDIOIF( hvsd,
                                 VSD_SAVE,
                                 0L,
                                 0 );

     return(rc);</pre>




=== VSD_SAVE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Example Code 
Glossary </pre>




=== VSD_SET ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Glossary </pre>

-----

This command allows an application to modify the settings of the VSD.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SET.

'''ulFlags'''([[00998.htm|ULONG]]) The following flags can be used with VSD_SET.

VSD_SETAUDIOATTRIBUTES See [[00433.htm|VSD_SETAUDIOATTRIBUTES]]

VSD_SETCONNECTOR See [[00442.htm|VSD_SETCONNECTOR]]

VSD_SETDATATYPE See [[00451.htm|VSD_SETDATATYPE]]

VSD_SETMIXCONNECTIONS See [[00460.htm|VSD_SETMIXCONNECTIONS]]

VSD_SETMIXCONTROL See [[00469.htm|VSD_SETMIXCONTROL]]

VSD_SETMONITOR See [[00478.htm|VSD_SETMONITOR]]

VSD_SETVOLUME See [[00487.htm|VSD_SETVOLUME]]

'''pRequest'''([[01203.htm|PVOID]]) Pointer value varies according to the value of ''ulFlags''.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_INVALID_HVSD The ''hvsd''(VSD handle) is not valid. Verify that the ''hvsd''matches the one provided on the [[00290.htm|VSD_OPEN]].





=== VSD_SET Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to VSD.





=== VSD_SET Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SET.





=== VSD_SET Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following flags can be used with VSD_SET.

VSD_SETAUDIOATTRIBUTES See [[00433.htm|VSD_SETAUDIOATTRIBUTES]]

VSD_SETCONNECTOR See [[00442.htm|VSD_SETCONNECTOR]]

VSD_SETDATATYPE See [[00451.htm|VSD_SETDATATYPE]]

VSD_SETMIXCONNECTIONS See [[00460.htm|VSD_SETMIXCONNECTIONS]]

VSD_SETMIXCONTROL See [[00469.htm|VSD_SETMIXCONTROL]]

VSD_SETMONITOR See [[00478.htm|VSD_SETMONITOR]]

VSD_SETVOLUME See [[00487.htm|VSD_SETVOLUME]]





=== VSD_SET Parameter - pRequest ===

'''pRequest'''([[01203.htm|PVOID]]) Pointer value varies according to the value of ''ulFlags''.





=== VSD_SET Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_INVALID_HVSD The ''hvsd''(VSD handle) is not valid. Verify that the ''hvsd''matches the one provided on the [[00290.htm|VSD_OPEN]].





=== VSD_SET - Syntax ===

This command allows an application to modify the settings of the VSD.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SET.

'''ulFlags'''([[00998.htm|ULONG]]) The following flags can be used with VSD_SET.

VSD_SETAUDIOATTRIBUTES See [[00433.htm|VSD_SETAUDIOATTRIBUTES]]

VSD_SETCONNECTOR See [[00442.htm|VSD_SETCONNECTOR]]

VSD_SETDATATYPE See [[00451.htm|VSD_SETDATATYPE]]

VSD_SETMIXCONNECTIONS See [[00460.htm|VSD_SETMIXCONNECTIONS]]

VSD_SETMIXCONTROL See [[00469.htm|VSD_SETMIXCONTROL]]

VSD_SETMONITOR See [[00478.htm|VSD_SETMONITOR]]

VSD_SETVOLUME See [[00487.htm|VSD_SETVOLUME]]

'''pRequest'''([[01203.htm|PVOID]]) Pointer value varies according to the value of ''ulFlags''.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_INVALID_HVSD The ''hvsd''(VSD handle) is not valid. Verify that the ''hvsd''matches the one provided on the [[00290.htm|VSD_OPEN]].





=== VSD_SET - Remarks ===

This messages uses flags to specify what to set on the adapter.





=== VSD_SET - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Remarks 
Glossary </pre>




=== VSD_SETAUDIOATTRIBUTES ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command sets the audio attribute settings. A valid length must be placed in the ''ulLength''field of the [[01119.htm|VSD_ AUDIOATTRIBUTES_PARMS]]structure. The audio setting to modify (such as treble, bass, and so on) must be placed in the ''ulFlags''field of the [[01119.htm|VSD_ AUDIOATTRIBUTES_PARMS]]structure with the actual corresponding setting in the ''ulValue''field. The value should be between 0 and 100. The ''ulDelay''indicates the length of time over which this effect should take place.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SET.

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETAUDIOATTRIBUTES.

'''pRequest'''([[01119.htm|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[01119.htm|VSD_AUDIOATTRIBUTES_ PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_SETAUDIOATTRIBUTES Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETAUDIOATTRIBUTES Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SET.





=== VSD_SETAUDIOATTRIBUTES Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETAUDIOATTRIBUTES.





=== VSD_SETAUDIOATTRIBUTES Parameter - pRequest ===

'''pRequest'''([[01119.htm|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[01119.htm|VSD_AUDIOATTRIBUTES_ PARMS]]structure.





=== VSD_SETAUDIOATTRIBUTES Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_SETAUDIOATTRIBUTES - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command sets the audio attribute settings. A valid length must be placed in the ''ulLength''field of the [[01119.htm|VSD_ AUDIOATTRIBUTES_PARMS]]structure. The audio setting to modify (such as treble, bass, and so on) must be placed in the ''ulFlags''field of the [[01119.htm|VSD_ AUDIOATTRIBUTES_PARMS]]structure with the actual corresponding setting in the ''ulValue''field. The value should be between 0 and 100. The ''ulDelay''indicates the length of time over which this effect should take place.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_SET.

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETAUDIOATTRIBUTES.

'''pRequest'''([[01119.htm|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[01119.htm|VSD_AUDIOATTRIBUTES_ PARMS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_MISSING_PARAMETER One or more parameters are missing.





=== VSD_SETAUDIOATTRIBUTES - Example Code ===

The following code illustrates how to set audio attribute information.

<pre class="western">VSD_AUDIOATTRIBUTES_PARMS   vsdAttr;

    /* Prime the structure with necessary values */
vsdAttr.ulLength = sizeof (VSD_AUDIOATTRIBUTES_PARMS);
vsdAttr.ulFlags = VSD_BASS;
vsdAttr.ulValue = 100;

    /*---------------------------------------------
     * Ask the VSD to either set or query an audio
     * attribute.  The caller determines whether
     * to set or query via the command variable.
     *---------------------------------------------*/

     rc = pInstance-&gt;pfnAUDIOIF((HVSD)pInstance-&gt;hvsd,
                                VSD_SET,
                                VSD_SETAUDIOATTRIBUTES,
                                (PVOID)&amp;vsdAttr);</pre>




=== VSD_SETAUDIOATTRIBUTES - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_SETCONNECTOR ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command enables or disables a connector. (A connector can be a hardware or software connection on the device the VSD is controlling.) Note that enabling a connector can by default, disable another connector. For further information regarding connectors, refer to the MCI_CONNECTOR command in the ''OS/2 Multimedia Programming Reference''. Additional connectors can be found in MCIOS2.H.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETCONNECTOR.

'''pRequest'''([[01159.htm|PVSD_CONNECTOR_PARMS]]) A pointer to the [[01159.htm|VSD_CONNECTOR_PARMS]]structure.

The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the ''fEnabled''field. A valid connector must be placed in the ''ulConn_Type''field and a valid index in the ''ulIndex''field.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_UNSUPPORTED_CONNECTOR Connector setting is not supported.

VSDERR_INVALID_CONNECTOR Connector setting is invalid.





=== VSD_SETCONNECTOR Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETCONNECTOR Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].





=== VSD_SETCONNECTOR Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETCONNECTOR.





=== VSD_SETCONNECTOR Parameter - pRequest ===

'''pRequest'''([[01159.htm|PVSD_CONNECTOR_PARMS]]) A pointer to the [[01159.htm|VSD_CONNECTOR_PARMS]]structure.

The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the ''fEnabled''field. A valid connector must be placed in the ''ulConn_Type''field and a valid index in the ''ulIndex''field.





=== VSD_SETCONNECTOR Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_UNSUPPORTED_CONNECTOR Connector setting is not supported.

VSDERR_INVALID_CONNECTOR Connector setting is invalid.





=== VSD_SETCONNECTOR - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command enables or disables a connector. (A connector can be a hardware or software connection on the device the VSD is controlling.) Note that enabling a connector can by default, disable another connector. For further information regarding connectors, refer to the MCI_CONNECTOR command in the ''OS/2 Multimedia Programming Reference''. Additional connectors can be found in MCIOS2.H.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETCONNECTOR.

'''pRequest'''([[01159.htm|PVSD_CONNECTOR_PARMS]]) A pointer to the [[01159.htm|VSD_CONNECTOR_PARMS]]structure.

The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the ''fEnabled''field. A valid connector must be placed in the ''ulConn_Type''field and a valid index in the ''ulIndex''field.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_UNSUPPORTED_CONNECTOR Connector setting is not supported.

VSDERR_INVALID_CONNECTOR Connector setting is invalid.





=== VSD_SETCONNECTOR - Example Code ===

The following code illustrates how to set the state of the connector.

<pre class="western">    HVSD                   hvsd;
    VSD_CONNECTOR_PARMS    vsdConn;

    vsdConn.ulConn_Type = pConnector-&gt;ulConnectorType;
    vsdConn.ulIndex = pConnector-&gt;ulConnectorIndex;
    vsdConn.fEnabled = VSD_DISABLE;

    /*--------------------------------------------------
     * Tell the VSD that we want to disable a connector.
     *--------------------------------------------------*/
    lError = pInstance-&gt;pfnNewVSD(hvsd,
                                  VSD_SET,
                                  VSD_SETCONNECTOR,
                                  (PVOID)&amp;vsdConn);</pre>




=== VSD_SETCONNECTOR - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_SETDATATYPE ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command sets the current data type that the device is dealing with.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETDATATYPE.

'''pRequest'''([[01124.htm|PVSD_AUDIODATATYPE_PARMS]]) Input. Pointer to a [[01124.htm|VSD_AUDIODATATYPE_ PARMS]]structure.

'''Note:'''Every field in the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure contains a numeric value except for ''ulOperation''. This field contains either VSD_ PRODUCE for recording or VSD_CONSUME for playback. The VSD is responsible for filling in the ''ulBlockAlignment'', ''ulDataSubType'', and ''ulAverageBytesPerSec''fields in the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure.

The ''ulFlags''field of the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure contains a flag for each field in the structure that can be set. Every field has a flag except for the ''ulOperation''field. The ''ulOperation''field is valid for every call.

The [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure must contain at least one of the following flags:

�VSD_MODE

�VSD_CHANNELS

�VSD_SAMPLESPERSEC

�VSD_OPERATION

�VSD_BITSPERSAMPLE

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_SETDATATYPE Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETDATATYPE Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].





=== VSD_SETDATATYPE Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETDATATYPE.





=== VSD_SETDATATYPE Parameter - pRequest ===

'''pRequest'''([[01124.htm|PVSD_AUDIODATATYPE_PARMS]]) Input. Pointer to a [[01124.htm|VSD_AUDIODATATYPE_ PARMS]]structure.

'''Note:'''Every field in the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure contains a numeric value except for ''ulOperation''. This field contains either VSD_ PRODUCE for recording or VSD_CONSUME for playback. The VSD is responsible for filling in the ''ulBlockAlignment'', ''ulDataSubType'', and ''ulAverageBytesPerSec''fields in the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure.

The ''ulFlags''field of the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure contains a flag for each field in the structure that can be set. Every field has a flag except for the ''ulOperation''field. The ''ulOperation''field is valid for every call.

The [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure must contain at least one of the following flags:

�VSD_MODE

�VSD_CHANNELS

�VSD_SAMPLESPERSEC

�VSD_OPERATION

�VSD_BITSPERSAMPLE





=== VSD_SETDATATYPE Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_SETDATATYPE - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command sets the current data type that the device is dealing with.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETDATATYPE.

'''pRequest'''([[01124.htm|PVSD_AUDIODATATYPE_PARMS]]) Input. Pointer to a [[01124.htm|VSD_AUDIODATATYPE_ PARMS]]structure.

'''Note:'''Every field in the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure contains a numeric value except for ''ulOperation''. This field contains either VSD_ PRODUCE for recording or VSD_CONSUME for playback. The VSD is responsible for filling in the ''ulBlockAlignment'', ''ulDataSubType'', and ''ulAverageBytesPerSec''fields in the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure.

The ''ulFlags''field of the [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure contains a flag for each field in the structure that can be set. Every field has a flag except for the ''ulOperation''field. The ''ulOperation''field is valid for every call.

The [[01124.htm|VSD_AUDIODATATYPE_PARMS]]structure must contain at least one of the following flags:

�VSD_MODE

�VSD_CHANNELS

�VSD_SAMPLESPERSEC

�VSD_OPERATION

�VSD_BITSPERSAMPLE

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.





=== VSD_SETDATATYPE - Example Code ===

The following code illustrates how to set the data type, sampling rate, channels, and bits per sample for an audio VSD.

<pre class="western">HVSD                     hvsd;
VSD_AUDIODATATYPE_PARMS  AudioDatatype;
PMMAUDIOHEADER           pmmaudioheader;
AudioDatatype.ulDataType = pmmaudioheader-&gt;mmXWAVHeader.WAVEHeader.usFormatTag;
AudioDatatype.ulBitsPerSample = pmmaudioheader-&gt;mmXWAVHeader.WAVEHeader.usBitsPerSample;
AudioDatatype.ulSamplingRate = pmmaudioheader-&gt;mmXWAVHeader.WAVEHeader.usSamplesPerSec;
AudioDatatype.ulChannels = pmmaudioheader-&gt;mmXWAVHeader.WAVEHeader.usChannels;
AudioDatatype.ulOperation = VSD_PLAY;
AudioDatatype.ulFlags = VSD_MODE|VSD_CHANNELS|VSD_SAMPLESPERSEC|
                        VSD_OPERATION|VSD_BITSPERSAMPLE;

   rc = pInstance-&gt;pfnNewVSD(hvsd,
                             VSD_SET,
                             VSD_SETDATATYPE,
                    (PVOID)&amp;AudioDatatype);
   if(rc)
     {
     return(rc)
     }</pre>




=== VSD_SETDATATYPE - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_SETMIXCONNECTIONS ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command routes the audio output of a connector to a particular output circuitry (that is, pass thru, internal mixer circuitry, and so on). For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMIXCONNECTIONS.

'''pRequest'''([[00812.htm|PLINECONNECTIONS]]) A pointer to the [[00812.htm|LINECONNECTIONS]]structure.

The caller must fill in the ''ulConnections''and the ''ulLine''fields of the [[00812.htm|LINECONNECTIONS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_SETMIXCONNECTIONS Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETMIXCONNECTIONS Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].





=== VSD_SETMIXCONNECTIONS Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMIXCONNECTIONS.





=== VSD_SETMIXCONNECTIONS Parameter - pRequest ===

'''pRequest'''([[00812.htm|PLINECONNECTIONS]]) A pointer to the [[00812.htm|LINECONNECTIONS]]structure.

The caller must fill in the ''ulConnections''and the ''ulLine''fields of the [[00812.htm|LINECONNECTIONS]]structure.





=== VSD_SETMIXCONNECTIONS Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_SETMIXCONNECTIONS - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command routes the audio output of a connector to a particular output circuitry (that is, pass thru, internal mixer circuitry, and so on). For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMIXCONNECTIONS.

'''pRequest'''([[00812.htm|PLINECONNECTIONS]]) A pointer to the [[00812.htm|LINECONNECTIONS]]structure.

The caller must fill in the ''ulConnections''and the ''ulLine''fields of the [[00812.htm|LINECONNECTIONS]]structure.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_SETMIXCONNECTIONS - Example Code ===

The following code illustrates how to route the output of a connector to the internal mixer circuitry.

<pre class="western">  LINECONNECTIONS   mixinfo;

  mixinfo.ulLine = SOURCE_SYNTHESIZER;
  mixinfo.ulConnection = SINK_SPEAKER;
  rc = pInstance-&gt;((HVSD)pInstance-&gt;hvsd,
                   VSD_SET,
                   VSD_SETMIXCONNECTIONS,
                   (PVOID)&amp;mixinfo);

  return(rc);</pre>




=== VSD_SETMIXCONNECTIONS - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_SETMIXCONTROL ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command enables an application to set the current state of a particular line. For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMIXCONTROL.

'''pRequest'''([[00930.htm|PMIXERCONTROL]]) A pointer to the [[00930.htm|MIXERCONTROL]]structure.

The ''ulControl''field of the [[00930.htm|MIXERCONTROL]]structure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting and the low-order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout. The ''ulLine''field must also be filled in.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_SETMIXCONTROL Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETMIXCONTROL Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].





=== VSD_SETMIXCONTROL Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMIXCONTROL.





=== VSD_SETMIXCONTROL Parameter - pRequest ===

'''pRequest'''([[00930.htm|PMIXERCONTROL]]) A pointer to the [[00930.htm|MIXERCONTROL]]structure.

The ''ulControl''field of the [[00930.htm|MIXERCONTROL]]structure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting and the low-order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout. The ''ulLine''field must also be filled in.





=== VSD_SETMIXCONTROL Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_SETMIXCONTROL - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command enables an application to set the current state of a particular line. For further information about VSD mixer support and functions, see [[00069.htm|Audio Sample for Vendor-Specific Drivers]]and [[00567.htm|Mixer IOCtl Functions Introduction]]

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMIXCONTROL.

'''pRequest'''([[00930.htm|PMIXERCONTROL]]) A pointer to the [[00930.htm|MIXERCONTROL]]structure.

The ''ulControl''field of the [[00930.htm|MIXERCONTROL]]structure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting and the low-order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout. The ''ulLine''field must also be filled in.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:

VSDERR_MISSING_PARAMETER One or more parameters are missing.

VSDERR_INVALID_SOURCE Invalid source.

VSDERR_INVALID_SINK Invalid sink.

VSDERR_INVALID_CONNECTION Invalid connection.





=== VSD_SETMIXCONTROL - Example Code ===

The following code illustrates how to query the settings of an audio attributes for a particular connector.

<pre class="western">  MIXERCONTROL   MixerControl;
  USHORT         usBass;


  MixerControl.ulControl = MIX_SUPPORT_VOLUME;
  MixerControl.ulLine = SINK_LINE_OUT;
  MixerControl.ulSetting = 100;

  lError = pInstance-&gt;((HVSD)pInstance-&gt;hvsd,
                      VSD_SET,
                      VSD_SETMIXCONTROL,
                      (PVOID)&amp;MixerControl);

   return(lError);</pre>




=== VSD_SETMIXCONTROL - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_SETMONITOR ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command enables (MCI_TRUE) or disables (MCI_ FALSE) the audio monitor feature of the device.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMONITOR.

'''pRequest'''([[00998.htm|PULONG]]) Input. Set to MCI_TRUE or MCI_FALSE.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success.

VSDERR_SUCCESS The command was successful.





=== VSD_SETMONITOR Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETMONITOR Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].





=== VSD_SETMONITOR Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMONITOR.





=== VSD_SETMONITOR Parameter - pRequest ===

'''pRequest'''([[00998.htm|PULONG]]) Input. Set to MCI_TRUE or MCI_FALSE.





=== VSD_SETMONITOR Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error code indicating success.

VSDERR_SUCCESS The command was successful.





=== VSD_SETMONITOR - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command enables (MCI_TRUE) or disables (MCI_ FALSE) the audio monitor feature of the device.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETMONITOR.

'''pRequest'''([[00998.htm|PULONG]]) Input. Set to MCI_TRUE or MCI_FALSE.

'''rc'''([[00998.htm|ULONG]]) Error code indicating success.

VSDERR_SUCCESS The command was successful.





=== VSD_SETMONITOR - Example Code ===

The following code illustrates how to set the state of the VSD monitor.

<pre class="western">ULONG    ulSetOn;

   ulSetOn = MCI_TRUE;

   /* Tell the VSD to change monitor status */

   lError = prInstance-&gt;pfnAUDIOIF((HVSD)prInstance-&gt;pMix-&gt;hvsd
                           VSD_SET,
                           VSD_SETMONITOR,
                           (PVOID)lSetOn);</pre>




=== VSD_SETMONITOR - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== VSD_SETVOLUME ===


-----

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>

-----

This subcommand of the [[00424.htm|VSD_SET]]command sets the volume level as a percentage (0 - 100). If the value is not one of the supported volume levels, it is rounded up to the nearest supported level. The ''ulFlags''field indicates which fields are to be used.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETVOLUME.

'''pRequest'''([[01194.htm|PVSD_VOLUME_PARMS]]) Pointer to the [[01194.htm|VSD_VOLUME_PARMS]]structure.

The caller must fill in the ''ulVolume''field if VSD_VOLUME is specified. The caller must fill in the ''ulMasterAudio''field if VSD_MASTERVOLUME is specified. The caller must fill in the ''fMute''field with a boolean if VSD_ MUTE is specified. TRUE mutes the device; FALSE unmutes the device.

'''rc'''([[00998.htm|ULONG]]) Error codes indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_VOL_OUT_OF_RANGE Invalid volume level.





=== VSD_SETVOLUME Parameter - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.





=== VSD_SETVOLUME Parameter - ulFunc ===

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].





=== VSD_SETVOLUME Parameter - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETVOLUME.





=== VSD_SETVOLUME Parameter - pRequest ===

'''pRequest'''([[01194.htm|PVSD_VOLUME_PARMS]]) Pointer to the [[01194.htm|VSD_VOLUME_PARMS]]structure.

The caller must fill in the ''ulVolume''field if VSD_VOLUME is specified. The caller must fill in the ''ulMasterAudio''field if VSD_MASTERVOLUME is specified. The caller must fill in the ''fMute''field with a boolean if VSD_ MUTE is specified. TRUE mutes the device; FALSE unmutes the device.





=== VSD_SETVOLUME Return Value - rc ===

'''rc'''([[00998.htm|ULONG]]) Error codes indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_VOL_OUT_OF_RANGE Invalid volume level.





=== VSD_SETVOLUME - Syntax ===

This subcommand of the [[00424.htm|VSD_SET]]command sets the volume level as a percentage (0 - 100). If the value is not one of the supported volume levels, it is rounded up to the nearest supported level. The ''ulFlags''field indicates which fields are to be used.

This command is sent using [[00235.htm|VSDEntry]]as follows:

<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.

'''ulFunc'''([[00998.htm|ULONG]]) Set to [[00424.htm|VSD_SET]].

'''ulFlags'''([[00998.htm|ULONG]]) Set to VSD_SETVOLUME.

'''pRequest'''([[01194.htm|PVSD_VOLUME_PARMS]]) Pointer to the [[01194.htm|VSD_VOLUME_PARMS]]structure.

The caller must fill in the ''ulVolume''field if VSD_VOLUME is specified. The caller must fill in the ''ulMasterAudio''field if VSD_MASTERVOLUME is specified. The caller must fill in the ''fMute''field with a boolean if VSD_ MUTE is specified. TRUE mutes the device; FALSE unmutes the device.

'''rc'''([[00998.htm|ULONG]]) Error codes indicating success or the type of failure:

VSDERR_SUCCESS The command was successful.

VSDERR_VOL_OUT_OF_RANGE Invalid volume level.





=== VSD_SETVOLUME - Example Code ===

The following code illustrates how to set the volume on an audio VSD.

<pre class="western">VSD_VOLUME_PARMS   vsdVol;
   vsdVol.ulVolume = pInstance-&gt;ulVolume;
   vsdVol.ulMasterAudio  = pInstance-&gt;ulMasterVolume;
   vsdVol.fMute = pInstance-&gt;fMute;
   vsdVol.ulVectoredVolume  = pInstance-&gt;ulTime;
   vsdVol.ulFlags  = VSD_VOLUME | VSD_MASTERVOLUME;


   lError = prInstance-&gt;pfnAUDIOIF((HVSD)prInstance-&gt;pMix-&gt;hvsd
                           VSD_SET,
                           VSD_SETVOLUME,
                           (PVOID)&amp;vsdVol);</pre>




=== VSD_SETVOLUME - Topics ===

Select an item:

<pre class="western">Syntax
Returns 
Example Code 
Glossary </pre>




=== IOCtl Functions ===

OS/2 device drivers are used to access the I/O hardware. The ''IOCtl''functions provide a method for an application, or subsystem, to send device -specific control commands to a physical device driver. These IOCtls are subfunctions that are issued through the DosDevIOCtl function request. The DosDevIOCtl request can be used only by OS/2 applications; the INT 21h IOCtl request can be used only by DOS applications.

This reference describes audio (category 80h) and video (category 140h) IOCtls.





=== Audio IOCtl Functions ===

Audio device drivers are controlled through input/output control (IOCtl) calls, which are used to instruct the audio device driver on the type of audio to use (for example, MIDI, 8- or 16-bit PCM, and so forth) and which operation to perform (for example, record, play, start, or pause). During audio playback, data is written to an audio device driver using standard file I/O functions. MIDI data is written in blocks containing timing information that enables the device driver to synchronize the data with its internal time base. Sampled audio data is output, sample-by-sample, at the specified sample rate. Therefore, data written to the device driver is queued until the correct time for it to be processed.

It is in the best interest of OS/2, MMPM/2, and the application that the audio IOCtls be used only for setting audio attributes and ''not''for passing audio data from an MMPM/2 application to the PDD. The preferred method of passing audio data is for the application to issue '''play'''and '''record'''commands using the media control interface. A logical media device is called, which in turn calls the stream programming interface. Data transfer takes place between a stream handler device driver and the PDD by means of the inter- device driver communications (IDC) interface.

Using the IDC method of data transfer relieves applications from the burden of allocating data buffer memory and monitoring the flow of data. The messages that comprise the IDC interface can be found in [[00154.htm|DDCMD Messages]]and [[00211.htm|SHD Messages]].

Audio IOCtl parameters are passed to and from a device driver in a data area containing one or more 16-bit USHORT parameters. The first parameter always is the Request ID. Subsequent USHORTs pass data to, or receive data from, the device driver. The generic IOCtl interface uses two data-passing parameters, the ''parameter packet''and the ''data packet''. For audio IOCtls, the data packet parameter is a pointer to a data structure containing the data necessary to perform the command. The parameter packet is not used.

The audio IOCtls listed in the following table are category 80h (user defined):

<pre class="western">/-----------------------------------------------------------------\
|Function No.  |Function             |Description                 |
|--------------+---------------------+----------------------------|
|40h           |AUDIO_INIT           |Initialize audio device     |
|              |                     |driver.                     |
|--------------+---------------------+----------------------------|
|41h           |AUDIO_STATUS         |Obtain status of audio      |
|              |                     |hardware.                   |
|--------------+---------------------+----------------------------|
|42h           |AUDIO_CONTROL        |Control audio adapter.      |
|--------------+---------------------+----------------------------|
|43h           |AUDIO_BUFFER         |Determine buffer status.    |
|--------------+---------------------+----------------------------|
|44h           |AUDIO_LOAD           |Load DSP code.              |
|--------------+---------------------+----------------------------|
|45h           |AUDIO_WAIT           |Suspend program operation.  |
|--------------+---------------------+----------------------------|
|46h           |AUDIO_HPI            |Access high-performance     |
|              |                     |interface.                  |
|--------------+---------------------+----------------------------|
|47h           |AUDIO_UPDATE         |Update buffer information.  |
|--------------+---------------------+----------------------------|
|48H           |AUDIO_CAPABILITY     |Determine supported audio   |
|              |                     |settings.                   |
|--------------+---------------------+----------------------------|
|52H           |                     |reserved                    |
|--------------+---------------------+----------------------------|
|53H           |                     |reserved                    |
|--------------+---------------------+----------------------------|
|54H           |                     |reserved                    |
|--------------+---------------------+----------------------------|
|55H           |                     |reserved                    |
|--------------+---------------------+----------------------------|
|60H           |MIX_GETCONNECTIONS   |Determine if line is        |
|              |                     |enabled.                    |
|--------------+---------------------+----------------------------|
|61H           |MIX_SETCONNECTIONS   |Enable   a   line   to   the          | 
|                 |                         | Record / monitor   circuitry .     | 
| ---------- ---- + ---------- ---------- - + ---------- ---------- -------- | 
| 62H              | MIX _ GETLINEINFO        | Determine   line   capabilities . | 
| ---------- ---- + ---------- ---------- - + ---------- ---------- -------- | 
| 63H              | MIX _ GETCONTROL         | Get   current   state   of   a   line . | 
| ---------- ---- + ---------- ---------- - + ---------- ---------- -------- | 
| 64H              | MIX _ SETCONTROL         | Set   current   state   of   a   line . | 
\ ---------- ---- - ---------- ---------- - - ---------- ---------- -------- / </pre>
'''Note:'''This chapter documents AudioDD IOCTLs that could be sent to MMPM/2 device drivers.

To support MMPM/2 the following IOCTLs are necessary:

AUDIO_INIT Required for all MMPM/2 device drivers. <br />AUDIO_CONTROL Required for all MMPM/2 device drivers. <br />AUDIO_LOAD Optional, used to load DSP tasks.

<br />MIXDM_GETCONNECTIONS Enhanced mixing IOCTLs (new) <br />MIXDM_SETCONNECTIONS <br />MIXDM_GETLINEONFO <br />MIXDM_GETCONTROL <br />MIXDM_SETCONTROL

<br />AUDIO_CAPABILITY Used to simplify install (new)

The remaining IOCtls documented in this chapter are provided as reference for device driver writers who wish to support AudioDD knowledgeable applications. These applications include IBM Linkway Live and early versions of IBM AVC (Audio Visual Connection).





=== AUDIO_INIT (40h) - Initialize Audio Device Driver ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_INIT (40h) <br />'''Description:'''<br />Initialize Audio Device Driver

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>

-----

This IOCtl enables an application to tell the audio device driver which operation and audio type to use. It does this by initializing the appropriate [[00877.htm|MCI_AUDIO_INIT]]fields to the desired values and calling AUDIO_ INIT.





=== AUDIO_INIT (40h) - Description ===

This IOCtl enables an application to tell the audio device driver which operation and audio type to use. It does this by initializing the appropriate [[00877.htm|MCI_AUDIO_INIT]]fields to the desired values and calling AUDIO_ INIT.





=== AUDIO_INIT (40h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_INIT (40h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _init {
  LONG           lSRate;
  LONG           lBitsPerSRate;
  LONG           lBsize;
  SHORT          sMode;
  SHORT          sChannels;
  LONG           lResolution;
  CHAR           abLoadPath[LOAD_PATH];
  ULONG          ulFlags;
  ULONG          ulOperation;
  SHORT          sReturnCode;
  SHORT          sSlotNumber;
  SHORT          sDeviceID;
  VOID FAR      *pvReserved;
  ULONG          ulVersionLevel;
} MCI_AUDIO_INIT;

typedef   MCI _ AUDIO _ INIT   FAR   * LPMCI _ AUDIO _ INIT ; </pre>






=== AUDIO_INIT (40h) - Data Packet Format ===



<pre class="western">/---------------------------------------------\
|Field                    C Datatype          |
|---------------------------------------------|
|Pointer to structure     LPMCI_AUDIO_INIT    |
\---------------------------------------------/</pre>




=== AUDIO_INIT (40h) - Returns ===

If the audio device driver can satisfy the request as specified, it returns ''0''. If the request cannot be performed as specified, the audio device driver fills in the [[00877.htm|MCI_AUDIO_INIT]]fields with the supported values that most closely approximate the values specified by the user, sets the BESTFIT _PROVIDED bit in ''ulFlags'', and returns ''0''to the application.

Refer to the ''OS/2 Control Program Guide and Reference''for more information on the return code for DosDevIOCtl.





=== AUDIO_INIT (40h) - Remarks ===

Before calling AUDIO_INIT, the application must have opened the audio device driver. If the application specifies invalid data in the [[00877.htm|MCI_AUDIO_ INIT]], the device driver probably will not return an error. Instead, one of its supported modes will return with the BESTFIT_PROVIDED bit set in ''ulFlags''of the [[00877.htm|MCI_AUDIO_INIT]]structure and the fields filled in. If, after examination of the returned values, the application is satisfied with the approximation, it can continue. Otherwise, it should use other values and reissue AUDIO_INIT.

Some audio devices are capable of performing more than one audio operation at a time. Therefore, the device driver for such devices can permit more than one application to use the device at one time by allowing multiple Opens to be active. If the device can perform the operations requested by two applications at the same time, it will ''appear''to be two different audio devices. If the device cannot perform a requested operation because that operation is being performed for another application, it will return the OVERLOADED flag set in the ''sReturnCode''field.

'''Note:'''It is critical that the application check the returned ''ulFlags''and ''sReturnCode''fields before proceeding.

If an application is going to perform audio simultaneously on more than one track, the application should perform OPENs and AUDIO_INITs for both devices before issuing AUDIO_START for either device. This enables the device to select the correct DSP load module to support both tasks, when possible.





=== AUDIO_INIT (40h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_INIT (40h) <br />'''Description:'''<br />Initialize Audio Device Driver

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>




=== AUDIO_STATUS (41h) - Obtain Status of Audio Hardware ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_STATUS (41h) <br />'''Description:'''<br />Obtain Status of Audio Hardware

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>

-----

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl enables an application to obtain the current state of the audio hardware for a particular track.





=== AUDIO_STATUS (41h) - Description ===

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl enables an application to obtain the current state of the audio hardware for a particular track.





=== AUDIO_STATUS (41h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_STATUS (41h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _stat {
  LONG                   lSRate;
  LONG                   lBitsPerSRate;
  LONG                   lBsize;
  SHORT                  sMode;
  SHORT                  sChannels;
  ULONG                  ulFlags;
  ULONG                  ulOperation;
  MCI_AUDIO_CHANGE       rAudioChange;
} MCI_AUDIO_STATUS;

typedef   MCI _ AUDIO _ STATUS   FAR   * LPMCI _ AUDIO _ STATUS ; </pre>






=== AUDIO_STATUS (41h) - Data Packet Format ===



<pre class="western">/-----------------------------------------------\
|Field                    C Datatype            |
|-----------------------------------------------|
|Pointer to structure     LPMCI_AUDIO_STATUS    |
\-----------------------------------------------/</pre>




=== AUDIO_STATUS (41h) - Returns ===

The values associated with the current audio mode are returned in the fields, ''lSRate'', ''lBitsPerSRate'', ''lBsize'', ''sMode'', ''sChannels'', and ''ulFlags''of the [[00906.htm|MCI_AUDIO_STATUS]]structure. The [[00845.htm|MCI_AUDIO_CHANGE]]data structure contains the current input, output, monitor, volume, balance, and tone control settings.

Refer to the ''OS/2 Control Program Guide and Reference''for more information on the return code for DosDevIOCtl.





=== AUDIO_STATUS (41h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_STATUS (41h) <br />'''Description:'''<br />Obtain Status of Audio Hardware

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>




=== AUDIO_CONTROL (42h) - Control Audio Adapter ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_CONTROL (42h) <br />'''Description:'''<br />Control Audio Adapter

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>

-----

This IOCtl is used to change the state of the adapter or selected characteristics of the adapter. The ''adapter state''is changed by the following ''usIOCtlRequest''values:

�AUDIO_START (Not required for MMPM/2.) <br />�AUDIO_STOP (Not required for MMPM/2.) <br />�AUDIO_PAUSE (Not required for MMPM/2.) <br />�AUDIO_RESUME (Not required for MMPM/2.) <br />�AUDIO_CHANGE

''Adapter characteristics''are changed by the ''usIOCtlRequest''value AUDIO_ CHANGE.





=== AUDIO_CONTROL (42h) - Description ===

This IOCtl is used to change the state of the adapter or selected characteristics of the adapter. The ''adapter state''is changed by the following ''usIOCtlRequest''values:

�AUDIO_START (Not required for MMPM/2.) <br />�AUDIO_STOP (Not required for MMPM/2.) <br />�AUDIO_PAUSE (Not required for MMPM/2.) <br />�AUDIO_RESUME (Not required for MMPM/2.) <br />�AUDIO_CHANGE

''Adapter characteristics''are changed by the ''usIOCtlRequest''value AUDIO_ CHANGE.





=== AUDIO_CONTROL (42h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_CONTROL (42h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _MCI_AUDIO_CONTROL {
  USHORT       usIOCtlRequest;
  VOID        *pbRequestInfo;
  ULONG        ulPosition;
  SHORT        sReturnCode;
} MCI_AUDIO_CONTROL;

typedef   MCI _ AUDIO _ CONTROL   FAR   * LPMCI _ AUDIO _ CONTROL </pre>






=== AUDIO_CONTROL (42h) - Data Packet Format ===



<pre class="western">/------------------------------------------------\
|Field                    C Datatype             |
|------------------------------------------------|
|Pointer to structure     LPMCI_AUDIO_CONTROL    |
\------------------------------------------------/</pre>




=== AUDIO_CONTROL (42h) - Returns ===

If a requested input or output device is not supported by the audio device, ''sReturnCode''is set and an error returned.

Refer to the ''OS/2 Control Program Guide and Reference''for more information on the return code for DosDevIOCtl.





=== AUDIO_CONTROL (42h) - Remarks ===

The K12 version does not support ''ulPosition''values except for ''0''. Any pending AUDIO_CHANGE requests are discarded when [[00498.htm|AUDIO_INIT]]is issued.





=== AUDIO_CONTROL (42h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_CONTROL (42h) <br />'''Description:'''<br />Control Audio Adapter

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>




=== AUDIO_BUFFER (43h) - Determine Buffer Status ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_BUFFER (43h) <br />'''Description:'''<br />Determine Buffer Status

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>

-----

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl is used to determine the amount of data currently queued, device driver internal queue sizes, and whether an overrun or underrun has occurred. If either state has occurred, its respective bit is turned ''on''in the ''ulFlags''field.





=== AUDIO_BUFFER (43h) - Description ===

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl is used to determine the amount of data currently queued, device driver internal queue sizes, and whether an overrun or underrun has occurred. If either state has occurred, its respective bit is turned ''on''in the ''ulFlags''field.





=== AUDIO_BUFFER (43h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_BUFFER (43h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _buffer {
  ULONG       ulFlags;
  ULONG       ulReadBufSize;
  ULONG       ulWriteBufSize;
  ULONG       ulReadBufTime;
  ULONG       ulWriteBufTime;
  ULONG       ulReadBufMax;
  ULONG       ulWriteBufMax;
  ULONG       ulPosition;
  ULONG       ulPositionType;
  LONG        lReadBufCap;
  LONG        lWriteBufCap;
  LONG        lRequestBufCap;
} MCI_AUDIO_BUFFER;

typedef   MCI _ AUDIO _ BUFFER   FAR   * LPMCI _ AUDIO _ BUFFER ; </pre>






=== AUDIO_BUFFER (43h) - Data Packet Format ===



<pre class="western">/-----------------------------------------------\
|Field                    C Datatype            |
|-----------------------------------------------|
|Pointer to structure     LPMCI_AUDIO_BUFFER    |
\-----------------------------------------------/</pre>




=== AUDIO_BUFFER (43h) - Returns ===

The amount of data is expressed as the number of bytes currently in the queues. Notice that the amount of queue data that this IOCtl returns is accurate only at the point in time this value is determined. The amount of queued data can be different at any other point in time.

If the size of the buffer contents can be represented as an amount of time, that amount of time is returned in the fields ''ulReadBufTime''and ''ulWriteBufTime''. If not, the values returned are ''-1''. To help determine the optimal size of the Read and Write kernel buffer queues, the maximum number of bytes that these queues have ever contained is returned in ''ulReadBufMax''and ''ulWriteBufMax''.

Refer to the ''OS/2 Control Program Guide and Reference''for more information on the return code for DosDevIOCtl.





=== AUDIO_BUFFER (43h) - Remarks ===

This IOCtl is used to return data from the device driver and cannot be used to pass data to the device driver.





=== AUDIO_BUFFER (43h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_BUFFER (43h) <br />'''Description:'''<br />Determine Buffer Status

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>




=== AUDIO_LOAD (44h) - Load DSP Code ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_LOAD (44h) <br />'''Description:'''<br />Load DSP Code

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Remarks </pre>

-----

If the LOAD_CODE bit is set in the ''ulFlags''field of the [[00877.htm|MCI_AUDIO_INIT]]structure on an [[00498.htm|AUDIO_INIT]]request, the application must load the DSP code (specified by the device driver in the ''abLoadPath''field of [[00877.htm|MCI_AUDIO_INIT]]) into a buffer and issue an AUDIO_LOAD IOCtl request.





=== AUDIO_LOAD (44h) - Description ===

If the LOAD_CODE bit is set in the ''ulFlags''field of the [[00877.htm|MCI_AUDIO_INIT]]structure on an [[00498.htm|AUDIO_INIT]]request, the application must load the DSP code (specified by the device driver in the ''abLoadPath''field of [[00877.htm|MCI_AUDIO_INIT]]) into a buffer and issue an AUDIO_LOAD IOCtl request.





=== AUDIO_LOAD (44h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_LOAD (44h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _load {
  CHAR FAR      *pbBuffer;
  ULONG          ulSize;
  ULONG          ulFlags;
} MCI_AUDIO_LOAD;

typedef   MCI _ AUDIO _ LOAD   FAR   * LPMCI _ AUDIO _ LOAD ; </pre>






=== AUDIO_LOAD (44h) - Data Packet Format ===



<pre class="western">/---------------------------------------------\
|Field                    C Datatype          |
|---------------------------------------------|
|Pointer to structure     LPMCI_AUDIO_LOAD    |
\---------------------------------------------/</pre>




=== AUDIO_LOAD (44h) - Remarks ===

The ''pbBuffer''field of the [[00902.htm|MCI_AUDIO_LOAD]]structure must point to the start of the buffer where the code is loaded. The ''ulSize''field must be set to the number of bytes of loaded code (which is the size of the file). The ''ulFlags''field permits loading the file in multiple pieces. To do this, the first piece is written with the LOAD_START flag set and the last piece with the LOAD_END flag set. All intermediate pieces have both flags cleared. To load the file in a single piece, both flags are set. Notice that the first buffer written must be at least 128 bytes in length.





=== AUDIO_LOAD (44h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_LOAD (44h) <br />'''Description:'''<br />Load DSP Code

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Remarks </pre>




=== AUDIO_WAIT (45h) - Suspend program operation ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_WAIT (45h) <br />'''Description:'''<br />Suspend program operation

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>

-----

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl is used to suspend program operation until all previously written data is played by the device.





=== AUDIO_WAIT (45h) - Description ===

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl is used to suspend program operation until all previously written data is played by the device.





=== AUDIO_WAIT (45h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_WAIT (45h) - Data Packet Format ===

There are no parameters for AUDIO_WAIT. The packet pointer must be NULL.





=== AUDIO_WAIT (45h) - Returns ===

Refer to the ''OS/2 Control Program Guide and Reference''for a description of the return code for DosDevIOCtl.





=== AUDIO_WAIT (45h) - Remarks ===

The actual playing of audio data by the audio device can occur after the Write call is returned to the caller. If the caller does not want to continue program execution until all data is actually played by the device, it can issue AUDIO_WAIT. Some audio devices play audio data in discrete blocks. Data is not played unless at least a full block of data is available. If less than a block of data remains to be played, AUDIO_WAIT can be called, which causes the audio device driver to pad the data with silence, thus permitting the data to be played. The amount of data in the buffers can be determined using AUDIO_BUFFER.

AUDIO_WAIT does nothing if there are no prior calls to Write or [[00543.htm|AUDIO_HPI]]. Instead, it returns immediately to the caller.





=== AUDIO_WAIT (45h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_WAIT (45h) <br />'''Description:'''<br />Suspend program operation

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>




=== AUDIO_HPI (46h) - Access high-performance interface ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_HPI (46h) <br />'''Description:'''<br />Access high-performance interface

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>

-----

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl provides several high-performance interface functions and can be used to increase the size of the device driver's internal input and output buffers for higher bandwidth audio modes.





=== AUDIO_HPI (46h) - Description ===

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl provides several high-performance interface functions and can be used to increase the size of the device driver's internal input and output buffers for higher bandwidth audio modes.





=== AUDIO_HPI (46h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_HPI (46h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _hpi {
  VOID FAR                  *pvEntry ();
  VOID FAR                  *pvCallBack ();
  LPMCI_AUDIO_IOBUFFER       prXBuff;
  LPMCI_AUDIO_IOBUFFER       prRBuff;
  USHORT                     usFlags;
} MCI_AUDIO_HPI;

typedef   MCI _ AUDIO _ HPI   FAR   * LPMCI _ AUDIO _ HPI ; </pre>






=== AUDIO_HPI (46h) - Data Packet Format ===



<pre class="western">/--------------------------------------------\
|Field                    C Datatype         |
|--------------------------------------------|
|Pointer to structure     LPMCI_AUDIO_HPI    |
\--------------------------------------------/</pre>




=== AUDIO_HPI (46h) - Returns ===

An address is returned in ''pvEntry ()''in the [[00871.htm|MCI_AUDIO_HPI]]structure that can be used to invoke audio device driver functions directly. NULL is returned if this function is not available in the current environment.

Refer to the ''OS/2 Control Program Guide and Reference''for more information on the return code for DosDevIOCtl.





=== AUDIO_HPI (46h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_HPI (46h) <br />'''Description:'''<br />Access high-performance interface

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>




=== AUDIO_UPDATE (47h) - Update Buffer Information ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_UPDATE (47h) <br />'''Description:'''<br />Update Buffer Information

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>

-----

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl has two purposes:

�To condense the array of buffers by removing all buffers that have been processed from the array of buffers in the [[00892.htm|MCI_AUDIO_IOBUFFER]]data structure.

�To add a buffer to the list. The address and length of the buffer is passed down to the device driver in the [[00745.htm|audio_update]]structure.





=== AUDIO_UPDATE (47h) - Description ===

'''This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.'''

This IOCtl has two purposes:

�To condense the array of buffers by removing all buffers that have been processed from the array of buffers in the [[00892.htm|MCI_AUDIO_IOBUFFER]]data structure.

�To add a buffer to the list. The address and length of the buffer is passed down to the device driver in the [[00745.htm|audio_update]]structure.





=== AUDIO_UPDATE (47h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_UPDATE (47h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _audio_update {
  CHAR           iobuf_type;
  CHAR FAR      *buffer_address;
  ULONG          buffer_length;
  USHORT         rc;
  void FAR      *reserved;
} audio_update;

typedef   struct   audio _ update   FAR   * UPDATE ; </pre>






=== AUDIO_UPDATE (47h) - Data Packet Format ===



<pre class="western">/-------------------------------------\
|Field                    C Datatype  |
|-------------------------------------|
|Pointer to structure     UPDATE      |
\-------------------------------------/</pre>




=== AUDIO_UPDATE (47h) - Returns ===

On exit, ''rc''of the [[00745.htm|audio_update]]structure contains an error code if one of the DevHlp calls failed or the maximum number of buffers have already been queued.

Refer to the ''OS/2 Control Program Guide and Reference''for more information on the return code for DosDevIOCtl.





=== AUDIO_UPDATE (47h) - Remarks ===

To use this IOCtl, the application must use the high-performance interface. When [[00543.htm|AUDIO_HPI]]calls the device driver, an [[00892.htm|MCI_AUDIO_IOBUFFER]]structure with the maximum number of buffers that can be present must be passed. The ''iobuf-&gt;num_buffers''field should have the maximum number of buffers in it. Notice that there is a limit of 16 buffers that can be present.

It is not necessary for buffers passed in the buffer array of the [[00892.htm|MCI_AUDIO _IOBUFFER]]structure to contain addresses to buffers. Any or all of the buffers can point to NULL addresses and have lengths of ''0''. The device driver searches the list of the buffers, counts the number of non-NULL buffers, and sets the ''iobuf-&gt;num_buffers''to this number. All internal variables are initialized to allow access to that number of buffers. [[00543.htm|AUDIO_ HPI]]must be called again if this number changes.

When AUDIO_UPDATE is called, it removes all buffers in the current [[00892.htm|MCI_ AUDIO_IOBUFFER]]buffer array that have been processed. It then recalculates ''iobuf-&gt;num_buffers''and ''iobuf-&gt;size''(the total of all the buffer lengths). Notice that the buffer size must be an even number of bytes and less than 64KB in length.

If the [[00892.htm|MCI_AUDIO_IOBUFFER]]structure to be updated is to be transmitted, it is assumed that the buffer passed is full of data to be played. The ''pHead''pointer is updated to point to the beginning of the buffer following the buffer just added to the chain. The ''lCount''field is also updated by the device driver to include this buffer of data.

If ''buffer_address''is NULL, this IOCtl simply frees processed buffers and returns. To free a buffer, the device driver unlocks it if it is locked and sets the length to ''0''.





=== AUDIO_UPDATE (47h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_UPDATE (47h) <br />'''Description:'''<br />Update Buffer Information

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>




=== AUDIO_CAPABILITY (48h) - Determine If a Group of Audio Settings is Supported ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_CAPABILITY (48h) <br />'''Description:'''<br />Determine If a Group of Audio Settings is Supported

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code 
Remarks </pre>

-----

This IOCtl enables an application to determine if a particular group of audio settings can be supported. If the mode is supported, resource management information will be returned to the caller.





=== AUDIO_CAPABILITY (48h) - Description ===

This IOCtl enables an application to determine if a particular group of audio settings can be supported. If the mode is supported, resource management information will be returned to the caller.





=== AUDIO_CAPABILITY (48h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== AUDIO_CAPABILITY (48h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _MCI_AUDIO_CAPS {
  ULONG       ulLength;
  ULONG       ulSamplingRate;
  ULONG       ulChannels;
  ULONG       ulBitsPerSample;
  ULONG       ulDataType;
  ULONG       ulOperation;
  ULONG       ulSupport;
  ULONG       ulDataSubType;
  ULONG       ulResourceUnits;
  ULONG       ulResourceClass;
  ULONG       ulBlockAlign;
  BOOL        fCanRecord;
  ULONG       ulFlags;
  ULONG       ulCapability;
} MCI_AUDIO_CAPS;

typedef   MCI _ AUDIO _ CAPS   FAR   * PAUDIO _ CAPS ; </pre>






=== AUDIO_CAPABILITY (48h) - Data Packet Format ===



<pre class="western">/----------------------------------------\
|Field                    C Datatype     |
|----------------------------------------|
|Pointer to structure     PAUDIO_CAPS    |
\----------------------------------------/</pre>




=== AUDIO_CAPABILITY (48h) - Returns ===

SUPPORT_SUCCESS

UNSUPPORTED_RATE

UNSUPPORTED_CHANNELS

UNSUPPORTED_BPS

UNSUPPORTED_DATATYPE

UNSUPPORTED_OPERATION





=== AUDIO_CAPABILITY (48h) - Example Code ===

The following example code illustrates an application querying the audio device driver for its capabilities. If the device supports the desired mode , the application saves the information.

<pre class="western">  AUDIOCAPS   audiocaps;

  audiocaps.ulSamplingRate = 11025;
  audiocaps.ulBitsPerSample = 16;
  audiocaps.ulChannels = 2;
  audiocaps.ulDataType = DATATYPE_WAVEFORM;
  MAKE1616(&amp;audiocaps);
     rc = DosDevIOCtl(  handle,
                       AUDIO_IOCTL_CAT,
                       AUDIO_CAPABILITY,
                       0,
                       0,
                       0,
                       sizeof (audiocaps),
                       &amp;audiocaps,
                       (PVOID) &amp;ulParmLengthMax);
  if ( audiocaps.ulReturn )
    {
     // process success
     }
  else
     // process failure</pre>




=== AUDIO_CAPABILITY (48h) - Remarks ===

This information supersedes the information found in the VSD resource file. If this IOCtl is supported, a VSD resource DLL is not necessary.

The ''ulSamplingRate'', ''ulChannels'', ''ulBitsPerSample'', and ''ulDataType''fields of the [[00830.htm|MCI_AUDIO_CAPS]]structure must be filled in by the caller. The device driver will return SUPPORT_SUCCESS in the ''ulSupport''field if it supports the combination and ''non-zero''if it does not. If SUPPORT_SUCCESS is returned, the driver must also fill in the following fields of the [[00830.htm|MCI_ AUDIO_CAPS]]structure:

ulDataSubType. See valid subtypes in os2medef.h.

ulResourceClass. See Resource Classes and Resource Units for more information.

ulResourceUnits. See Resource Classes and Resource Units for more information.

ulBlockAlign. Block alignment of the data.

If ''ulSupport''contains a non-zero value, the driver should fill in the [[00830.htm|MCI_ AUDIO_CAPS]]structure with the nearest mode that matches the user's request (e.g. best-fit). The following fields must be updated for a best-fit:

�ulSamplingRate

�ulChannels

�ulBitsPerSample

�ulDataType

'''Resource Classes and Resource Units'''

When each audio device driver is installed in MMPM/2, the following three keywords are placed in the MMPM/2 INI file by the install routines:

�RESOURCEUNITS=

�RESOURCECLASSES=

�VALIDCOMBINATIONS=

Because MMPM/2 allows many applications to simultaneously open the audio card, it uses the following keywords to determine which applications can simultaneously use the audio device. Although the numbers are arbitrary and are defined on a device-by-device basis, device driver writers should use the numbering scheme described below:

The keyword '''RESOURCECLASSES'''indicates the different resource types available on the audio device. Vendors should provide a class for each data type that they support. For example, if the XYZ audio card can only play only PCM files, it would only have one resource class in the MMPM2.INI file , the PCM class. However, if the ABC card could play PCM, MIDI and ADPCM, it would have three classes in the MMPM2.INI file. The device driver should fill in the ulResourceClass field with the correct class for the current mode.

The keyword '''RESOURCEUNITS'''indicates the maximum number of instances that can be active on the card at any particular time. For example, if the XYZ card mentioned above had the ability to play three PCM files at the same time, the RESOURCEUNITS in the MMPM2.INI file for this card would be three. In contrast, the ABC card can only play one PCM and one MIDI at any one time. Therefore, its resource units should be two in the MMPM2.INI file. The device driver should fill in the ulResourceUnits field of the AUDIO_ CAPABILITY structure with the correct number of resources for the current mode (typically, one).

The keyword '''VALIDCOMBINATIONS'''informs MMPM/2 which RESOURCECLASS can be active at the same time on the audio device. For example, the XYZ card mentioned above can only play PCM files so it has no valid combinations. By contrast, the ABC card can play MDI and PCM at the same time; therefore, the VALIDCOMBINATIONS statement would state that the MIDI class could be active at the same time the PCM class is active and vise-versa. The valid combinations information is static and does not need to be returned by the device driver.





=== AUDIO_CAPABILITY (48h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />AUDIO_CAPABILITY (48h) <br />'''Description:'''<br />Determine If a Group of Audio Settings is Supported

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code 
Remarks </pre>




=== Mixer IOCtl Functions Introduction ===

The model of this mixer interface is based on a mixer device with a number of sources (such as microphone, PCM playback, and internal CD connector) which can be routed to a number of sinks or outputs (such as the recording circuitry or monitoring circuitry). The settings for the sources or sinks can be queried and set; and the capabilities of each input/output line can easily be determined.

<pre class="western">     /------------------------------------\
     |                                    |
     |    Sources          Sinks          |
     | /--------------------------------\ |
     | |               |                | |
     | |   Synth       |   Line Out     | |
     | |               |                | |
     | |   Line In     |   Speaker Out  | |
     | |               |                | |
     | |   Wave Data   |   Head Phones  | |
     | |               |                | |
     | |   Internal    |   Generic Out  | |
     | |   Audio       |                | |
     | |               |   Wave         | |
     | |   Microphone  |                | |
     | |               |   NULL         | |
     | |   PC Speaker  |                | |
     | |               |                | |
     | \--------------------------------/ |
     \------------------------------------/


     Standard sources are listed on the left.
     Standard sinks are listed on the right.
     The Generic Out includes line out, speaker
     out, and head phones.</pre>
The following IOCtls are recent additions to the AUDIO IOCTL category:

�[[00568.htm|MIX_GETCONNECTIONS]]<br />�[[00576.htm|MIX_SETCONNECTIONS]]<br />�[[00584.htm|MIX_GETLINEINFO]]<br />�[[00592.htm|MIX_GETCONTROL]]<br />�[[00600.htm|MIX_SETCONTROL]]





=== MIX_GETCONNECTIONS (60h) - Determine if Line is Enabled ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_GETCONNECTIONS (60h) <br />'''Description:'''<br />Determine if Line is Enabled

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>

-----

This IOCtl enables an application to determine if a particular mixer line is enabled.





=== MIX_GETCONNECTIONS (60h) - Description ===

This IOCtl enables an application to determine if a particular mixer line is enabled.





=== MIX_GETCONNECTIONS (60h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== MIX_GETCONNECTIONS (60h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _LINECONNECTIONS {
  ULONG       ulLength;
  ULONG       ulConnections;
  ULONG       ulLine;
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS ; </pre>
The caller is responsible for filling in the ''ulLine''field of the [[00812.htm|LINECONNECTIONS]]structure.

A bitmap describing the current connection structure will be returned in the ''ulConnections''field. Each ''on''bit indicates a connector which is enabled . For example, if the input line to be queried was set to 0 (i.e. the first line) and if that input line is connected to output line #0, bit 0 of ''ulConnections''will be set. Logically, connection information can only be maintained for a mixer with a maximum of 32 inputs and 32 outputs.





=== MIX_GETCONNECTIONS (60h) - Data Packet Format ===



<pre class="western">/---------------------------------------------\
|Field                    C Datatype          |
|---------------------------------------------|
|Pointer to structure     PLINECONNECTIONS    |
\---------------------------------------------/</pre>




=== MIX_GETCONNECTIONS (60h) - Returns ===

MIXERR_NOERR Successful operation.

MIXERR_INVALIDHANDLE Invalid handle specified.

MIXERR_INVALIDINPUT Invalid source specified.

MIXERR_INVALIDOUTPUT Invalid sink specified.

MIXERR_NOTSUPPORTED Mixer type unsupported.





=== MIX_GETCONNECTIONS (60h) - Example Code ===

The following code illustrates how to use MIX_GETCONNECTIONS.

<pre class="western">    HMIXER   hMix;
   LINECONNECTIONS  LineCon;
   /*-----------------------------------------
   * Find out the setting for the synth.
   *-----------------------------------------*/
   LineCon.ulLine = SOURCE_SYNTHESIZER;
   LineCon.ulLength = sizeof( LINECONNECTIONS);
    rc = DosDevIOCtl( hMix,
                      AUDIO_IOCTL_CATEGORY,
                      MIX_GETCONNECTIONS,
                      0,
                      0,
                      0,
                      sizeof (LINECONNECTIONS),
                      &amp;LineCon,
                      &amp;ulDataLengthOut);</pre>




=== MIX_GETCONNECTIONS (60h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_GETCONNECTIONS (60h) <br />'''Description:'''<br />Determine if Line is Enabled

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>




=== MIX_SETCONNECTIONS (61h) - Connect an Input Line to an Output Line ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_SETCONNECTIONS (61h) <br />'''Description:'''<br />Connect an Input Line to an Output Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>

-----

This IOCtl enables an application to connect an input line to an output line.





=== MIX_SETCONNECTIONS (61h) - Description ===

This IOCtl enables an application to connect an input line to an output line.





=== MIX_SETCONNECTIONS (61h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== MIX_SETCONNECTIONS (61h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _LINECONNECTIONS {
  ULONG       ulLength;
  ULONG       ulConnections;
  ULONG       ulLine;
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS ; </pre>
The caller is responsible for filling in the ''ulLine''and ''ulConnections''fields of the [[00812.htm|LINECONNECTIONS]]structure.





=== MIX_SETCONNECTIONS (61h) - Data Packet Format ===



<pre class="western">/---------------------------------------------\
|Field                    C Datatype          |
|---------------------------------------------|
|Pointer to structure     PLINECONNECTIONS    |
\---------------------------------------------/</pre>




=== MIX_SETCONNECTIONS (61h) - Returns ===

MIXERR_NOERR Successful operation.

MIXERR_INVALIDHANDLE Invalid handle specified.

MIXERR_INVALIDINPUT Invalid source specified.

MIXERR_INVALIDOUTPUT Invalid sink specified.

MIXERR_NOTSUPPORTED Mixer type unsupported.





=== MIX_SETCONNECTIONS (61h) - Example Code ===

The following code illustrates how to use MIX_SETCONNECTIONS.

<pre class="western">HMIXER   hMix;
    LINECONNECTIONS     mixinfo;
    PVOID     p16Info;
  /*-------------------------------------------
   * Find out the setting for the synth.
   *-----------------------------------------*/
   mixinfo.ulLine = SOURCE_SYNTHESIZER;
   mixinfo.ulConnection = SINK_SPEAKER;
      rc = DosDevIOCtl( hMix,
                        AUDIO_IOCTL_CATEGORY,
                        MIX_SETCONNECTIONS,
                        0,
                        0,
                        0,
                        sizeof (LINECONNECTIONS),
                        &amp;mixinfo,
                        &amp;ulDataLengthOut);</pre>




=== MIX_SETCONNECTIONS (61h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_SETCONNECTIONS (61h) <br />'''Description:'''<br />Connect an Input Line to an Output Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>




=== MIX_GETLINEINFO (62h) - Determine the Capabilities of a Line ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_GETLINEINFO (62h) <br />'''Description:'''<br />Determine the Capabilities of a Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>

-----

This IOCtl enables an application to determine the capabilities of a particular line. For instance, an application will call this function to determine if an individual line (for example, the microphone) allows adjustments for volume or balance.





=== MIX_GETLINEINFO (62h) - Description ===

This IOCtl enables an application to determine the capabilities of a particular line. For instance, an application will call this function to determine if an individual line (for example, the microphone) allows adjustments for volume or balance.





=== MIX_GETLINEINFO (62h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== MIX_GETLINEINFO (62h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _MIXERLINEINFO {
  ULONG       ulLength;
  ULONG       ulNumChannels;
  ULONG       ulSupport;
  ULONG       ulConnectionsPossible;
  ULONG       ulLine;
} MIXERLINEINFO;

typedef   MIXERLINEINFO   FAR   * PMIXERLINEINFO ; </pre>
The caller is responsible for filling in the ''ulLine''field of the [[00935.htm|MIXERLINEINFO]]structure.





=== MIX_GETLINEINFO (62h) - Data Packet Format ===



<pre class="western">/------------------------------------------\
|Field                    C Datatype       |
|------------------------------------------|
|Pointer to structure     MIXERLINEINFO    |
\------------------------------------------/</pre>




=== MIX_GETLINEINFO (62h) - Returns ===

MIXERR_NOERR Successful operation.

MIXERR_INVALIDHANDLE Invalid handle specified.

MIXERR_INVALIDINPUT Invalid source specified.

MIXERR_INVALIDOUTPUT Invalid sink specified.

MIXERR_NOTSUPPORTED Mixer type unsupported.





=== MIX_GETLINEINFO (62h) - Example Code ===

The following code illustrates how to use MIX_GETCONNECTIONS.

<pre class="western">   HMIXER   hMix;
   LINECONNECTIONS     mixinfo;
   /*-------------------------------------------
   * Find out the capabilities for setting the
   * synth input.
   *-----------------------------------------*/
   mixinfo.ulLine = SOURCE_SYNTHESIZER;
   rc = DosDevIOCtl( hMix,
                     AUDIO_IOCTL_CATEGORY,
                     MIX_GETLINEINFO,
                     0,
                     0,
                     0,
                     sizeof (LINECONNECTIONS),
                     &amp;mixinfo,
                     &amp;ulDataLengthOut);</pre>




=== MIX_GETLINEINFO (62h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_GETLINEINFO (62h) <br />'''Description:'''<br />Determine the Capabilities of a Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>




=== MIX_GETCONTROL (63h) - Get Current State of a Line ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_GETCONTROL (63h) <br />'''Description:'''<br />Get Current State of a Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>

-----

This IOCtl enables an application to get the current state of a particular line.





=== MIX_GETCONTROL (63h) - Description ===

This IOCtl enables an application to get the current state of a particular line.





=== MIX_GETCONTROL (63h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== MIX_GETCONTROL (63h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _MIXERCONTROL {
  ULONG       ulLength;
  ULONG       ulLine;
  ULONG       ulControl;
  ULONG       ulSetting;
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR   * PMIXERCONTROL ; </pre>
The caller is responsible for filling in the ''ulLine''field of the [[00930.htm|MIXERCONTROL]]structure.

The device driver should return the current setting of the line in the ''ulSetting''field of the [[00930.htm|MIXERCONTROL]]structure. For stereo controls, the high-order word should contain information for the left-channel and the low -order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout.





=== MIX_GETCONTROL (63h) - Data Packet Format ===



<pre class="western">/------------------------------------------\
|Field                    C Datatype       |
|------------------------------------------|
|Pointer to structure     PMIXERCONTROL    |
\------------------------------------------/</pre>




=== MIX_GETCONTROL (63h) - Returns ===

MIXERR_NOERR Successful operation.

MIXERR_INVALIDHANDLE Invalid handle specified.

MIXERR_INVALIDINPUT Invalid source specified.

MIXERR_INVALIDOUTPUT Invalid sink specified.

MIXERR_NOTSUPPORTED Mixer type unsupported.





=== MIX_GETCONTROL (63h) - Example Code ===

The following code illustrates how to use MIX_GETCONNECTIONS.

<pre class="western">   HMIXER   hMix;
   MIXERCONTROL        MixerControl;
   /*-------------------------------------------
   * Find out the setting for the synth.
   *-----------------------------------------*/
   MixerControl.ulLine= SOURCE_SYNTHESIZER;
   /* Ask vsd what is the current setting of the connector */
   MixerControl.ulControl = MIX_VOLUME;
   /* The controls current setting will be returned here */
         rc = DosDevIOCtl( hMix,
                     AUDIO_IOCTL_CATEGORY,
                     MIX_GETCONTROL,
                     MixerControl,
                     0,
                     0,
                     sizeof (MIXERCONTROL),
                     (PVOID) &amp;ulParmLengthMax,
                     &amp;ulDataLengthOut);</pre>




=== MIX_GETCONTROL (63h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_GETCONTROL (63h) <br />'''Description:'''<br />Get Current State of a Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>




=== MIX_SETCONTROL (64h) - Set State of a Mixer Line ===


-----

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_SETCONTROL (64h) <br />'''Description:'''<br />Set State of a Mixer Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>

-----

This IOCtl enables an application to set the current state of a particular line.





=== MIX_SETCONTROL (64h) - Description ===

This IOCtl enables an application to set the current state of a particular line.





=== MIX_SETCONTROL (64h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== MIX_SETCONTROL (64h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _MIXERCONTROL {
  ULONG       ulLength;
  ULONG       ulLine;
  ULONG       ulControl;
  ULONG       ulSetting;
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR   * PMIXERCONTROL ; </pre>
The caller is responsible for filling in the ''ulControl'', the ''ulLine'', and the ''ulSetting'', fields of the [[00930.htm|MIXERCONTROL]].

The device driver should return the current setting of the line in ''ulSetting''of the [[00930.htm|MIXERCONTROL]]structure. For stereo controls, the high- order word should contain information for the left-channel and the low- order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout.





=== MIX_SETCONTROL (64h) - Data Packet Format ===



<pre class="western">/------------------------------------------\
|Field                    C Datatype       |
|------------------------------------------|
|Pointer to structure     PMIXERCONTROL    |
\------------------------------------------/</pre>




=== MIX_SETCONTROL (64h) - Returns ===

MIXERR_NOERR Successful operation.

MIXERR_INVALIDHANDLE Invalid handle specified.

MIXERR_INVALIDINPUT Invalid source specified.

MIXERR_INVALIDOUTPUT Invalid sink specified.

MIXERR_NOTSUPPORTED Mixer type unsupported.





=== MIX_SETCONTROL (64h) - Example Code ===

The following code illustrates how to use MIX_GETCONNECTIONS.

<pre class="western">   HMIXER   hMix;
   MIXERCONTROL        MixerControl;

   /* Set the volume for the output device */

   MixerControl.ulControl = MIX__VOLUME;
   MixerControl.ulLine = SINK_LINE_OUT;
   MixerControl.ulSetting = 100;
     rc = DosDevIOCtl( hMix,
                     AUDIO_IOCTL_CATEGORY,
                     MIX_SETCONTROL,
                     0,
                     0,
                     0,
                     sizeof (MIXERCONTROL),
                     &amp;MixerControl,
                     &amp;ulDataLengthOut);</pre>




=== MIX_SETCONTROL (64h) - ===

'''Category:'''<br />AUDIO_IOCTL_CAT (80h) <br />'''Function:'''<br />MIX_SETCONTROL (64h) <br />'''Description:'''<br />Set State of a Mixer Line

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Example Code </pre>




=== IOCtl Examples ===

Examples of how IOCtls are used to communicate with an audio device driver are shown in this section for C programs running under OS/2, and for assembler language programs running under DOS. The following example is a pseudocode example that shows how an application records or plays back audio data.

<pre class="western"> Open audio device driver.
 If error opening driver:
     then end with error message.
 Issue AUDIO_INIT IOCtl to set type of audio data to play or record.
 If BESTFIT_PROVIDED flag set:
     check audio parameters returned by AUDIO_INIT IOCtl
     if returned parameters not acceptable:
         then end with message.
 If LOAD_CODE flag set:
     load file name returned in loadpath and issue AUDIO_LOAD IOCtl.

 Issue AUDIO_CONTROL CHANGE to initialize connections and control values.

 If recording:
     Open new file to write audio data to issue AUDIO_CONTROL START IOCtl.
     Do until Stop key pressed:
10
     Issue Read to get data.
     Write data to file.
     Do user interface or other processing.
     End Do.
 Issue AUDIO_CONTROL STOP IOCtl (optional).

 Else if playback:
     Open file containing data to play back.
     Issue AUDIO_BUFFER IOCtl to determine size of buffers.
     Read data from file and write data to fill audio DD buffer.
     Issue AUDIO_CONTROL START IOCtl.
     Do until end of file or Stop key pressed:
       Issue AUDIO_BUFFER IOCtl to determine free space in audio DD buffer.
       Read data from file.
       Write data to audio DD to fill audio DD buffer.
       Do user interface or other processing.
       End Do.
     Issue AUDIO_CONTROL STOP IOCtl (optional).
 Close data file.
 Close audio DD.</pre>
Under OS/2, IOCtls are called using the DosDevIOCtl function. The following example is an OS/2 [[00498.htm|AUDIO_INIT]]example.

<pre class="western">#define   INCL_DOSDEVICES

#include  &lt;os2.h&gt;
#include  &lt;io.h&gt;
#include  &lt;audiodd.h&gt;                 /* Defines for flags, and
                                         so forth                */

init_adpcmv(Handle)                   /* Initialize to record
                                         ADPCM voice             */

HFILE Handle;                         /* Handle returned from
                                         DosOpen()               */
{
   struct audio_init buffer;          /* I/O buffer (defined in
                                         audiodd.h)              */
   USHORT rc;

   buffer.srate = 11025;              /* Set rate = Voice mode   */
   buffer.bits_per_sample = 16;       /* 16-bits per sample       */
   buffer.bsize = 576;                /* Size of Voice mode data
                                         block                   */
   buffer.mode = ADPCM;               /* ADPCM mode              */
   buffer.channels = 1;               /* Mono                    */
   buffer.flags = FIXED;              /* Fixed block size data   */
   buffer.operation = RECORD;         /* Set up to record        */
   buffer.version_level = 0x01000018; /* Set version level       */

   rc = DosDevIOCtl(Handle, AUDIO_IOCTL_CAT, AUDIO_INIT, NULL, 0L,
        &amp;ParmLengthInOut, &amp;buffer, (LONG)sizeof(buffer),
        &amp;lDataLengthInOut);

   if(rc)
      return(rc);
}</pre>
Under DOS, IOCtls are called by using INT 21h Function 44h. The following is a DOS IOCtl example.

<pre class="western">INCLUDE AUDIODD.INC             ; Audio DD equates
/abort
; Read the queue status using AUDIO_BUFFER IOCtl

Handle  DW  ?                   ; Handle to open device (MIDIn$)
Buffer                          ; I/O Buffer
FLAGS           DD  0           ; Error condition flags
READ_BUF_SIZE   DD  0           ; Number of bytes currently in
                                ; Receive queue
WRITE_BUF_SIZE  DD  0           ; Number of bytes currently in
                                ; Transmit queue
READ_BUF_TIME   DD  0           ; Amount of data in Receive queue
                                ; in millisecs
WRITE_BUF_TIME  DD  0           ; Amount of data in Transmit queue
                                ; in millisecs
READ_BUF_MAX    DD  0           ; Maximum number of bytes ever in
                                ; Read queue
WRITE_BUF_MAX   DD  0           ; Maximum number of bytes ever in
                                ; Write queue
POSITION          DD    0              ;   Time   count   since   beginning   of 
                                    ;   operation 
POSITION _ TYPE     DD    0              ;   Specifies   the   type   of   position 
                                    ;   units 
READ _ BUF _ CAP      DD    0              ;   Capacity   of   Receive   queue ;   - 1   if 
                                    ;   variable 
WRITE _ BUF _ CAP     DD    0              ;   Capacity   of   Write   queue ;   - 1   if 
                                    ;   variable 
REQUEST _ BUF _ CAP   DD    0              ;   Maximum   number   of   requests   that 
                                    ;   can   be   queued 
Query _ Q _ Status : 

     MOV   AH , 44h                     ;   Function   call   -   IOCtl 
     MOV   AL , 0Ch                     ;   Indicate   generic   IOCtl   request 
     MOV   BX , Handle                  ;   Select   audio   device   handle   ( from 
                                    ;   previous   OPEN ) 
     MOV   CH , 80h                     ;   Generic   IOCtl   category 
     MOV   CL , 40h + AUDIO _ BUFFER       ;   Generic   IOCtl   Function   ID 
     MOV   DX , Offset   Buffer          ;   DS : DX   points   to   buffer 
     INT   21h                         ;   Issue   request   to   DOS 
     JC    Error                      ;   Error   code   in   AX   if   C   set 
     . 
     . 
     . </pre>




=== M-Audio MCI_AUDIO_INIT Parameters ===

The following table lists the [[00877.htm|MCI_AUDIO_INIT]]parameters for the operating modes currently supported by the IBM M-Audio Capture and Playback Adapter.

<pre class="western">/-------------------------------------------------------------------------------------------\
|Description         |Mode         |Bits  |Sample rate      |No.   |Block size |Flags       |
|                    |             |per   |                 |Chan. |           |            |
|                    |             |Sample|                 |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|MIDI                |MIDI         |-     |-                |-     |-          |-           |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|AVC Voice           |ADPCM        |16    |11025            |1     |576        |Fixed       |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|AVC Music           |ADPCM        |16    |22050            |1     |1128       |Fixed       |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|AVC Stereo          |ADPCM        |16    |22050            |2     |2256       |Fixed       |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|AVC High Quality    |ADPCM        |16    |44100            |1     |1128       |Fixed       |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|8 bit PCM           |PCM          |8     |8000, 11025,     |1     |560        |0           |
|                    |             |      |22050, 44100     |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|8 bit PCM stereo    |PCM          |8     |8000, 11025,     |2     |560        |0           |
|                    |             |      |22050, 44100     |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|16 bit PCM mono     |PCM          |16    |8000, 11025,     |1     |560        |TWOS_       |
|                    |             |      |22050, 44100     |      |           |COMPLEMENT  |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|16 bit PCM          |PCM          |16    |8000, 11025,     |2     |560        |TWOS_       |
|stereo              |             |      |22050, 44100     |      |           |COMPLEMENT  |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|8 bit mu-law mono   |MU_LAW       |8     |8000, 11025,     |1     |560        |0           |
|                    |             |      |22050, 44100     |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|8 bit mu-law stereo |MU_LAW       |8     |8000, 11025,     |2     |560        |0           |
|                    |             |      |22050            |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|8 bit A-law mono    |A_LAW        |8     |8000, 11025,     |1     |560        |0           |
|                    |             |      |22050, 44100     |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|8 bit A-law stereo  |A_LAW        |8     |8000, 11025,     |2     |560        |0           |
|                    |             |      |22050            |      |           |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|Claim Hardware      |CLAIM_HDWR   |-     |-                |-     |-          |-           |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|Source Mix          |SOURCE_MIX   |-     |-                |-     |-          |-           |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|Speech Viewer/2     |SPV2BCPCM    |16    |14700            |-     |426 tx /   |0           |
|BCPCM               |             |      |                 |      |426 rx     |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|Speech Viewer/2 PCM |SPV2PCM      |16    |14700            |-     |964 tx / 2 |0           |
|                    |             |      |                 |      |rx         |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|Speech Viewer/2     |SPV2NONE     |-     |-                |-     |256 tx /   |-           |
|Computations        |             |      |                 |      |138 rx     |            |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|ADPCM XA mono       |ADPCMXA      |16    |18900, 37800     |1     |1304       |0           |
|--------------------+-------------+------+-----------------+------+-----------+------------|
|ADPCM XA stereo     |ADPCMXA      |16    |18900, 37800     |2     |1304       |0           |
\-------------------------------------------------------------------------------------------/</pre>




=== Video IOCtl Functions ===

Video capture and/or playback device drivers are controlled through input/ output control (IOCtl) calls, which are used to query and instruct the video device driver. This interface has been used for numerous types and combinations of video devices-e.g., frame grabber, overlay, inlay, TV tuner , uncompressed playback, and compress video playback.

Video IOCtl parameters are passed to and from a device driver in a data area containing one or more 16-bit USHORT parameters. The first parameter is always the Request ID. Subsequent USHORTs are used to pass data to, or receive data from, the device driver. The generic IOCtl interface uses two parameters for passing data, the parameter packet and the data packet. For video IOCtls, the data packet parameter is a pointer to a data structure containing the data necessary to perform the command. The parameter packet is not used.





=== Capture ===

Video images can be captured one frame at a time when directed by the application. This type of capture mode is referred to as ''asymmetric''capture because the time between successive frames is not constant. The frame rate is determined by the length of time that the application delays between taking image snapshots. Asymmetric capture is performed with IOCtls only; the MMPM/2 streaming mechanism is not used.

Typically, a stream is established to read a series of ''moving''images from the device. This continuous capture mode is called ''symmetric''or ''real-time''capture, and is done at a constant frame rate and constant frame size. When established, a stream captures images continuously without assistance from the application code. A running stream cannot dynamically alter frame rate or size; but video quality attributes such as brightness, hue, and contrast can be altered dynamically. The command used in streaming capture can be found in the Device Driver Commands (DDCMD) messages and Stream-Handler Device (SHD) messages sections.

Streaming capture is used to make real-time movies and to monitor live video on frame-grabber cards.





=== Playback ===

Video playback is all done through the VCAI_PLAY IOCtl interface. Unlike record, this is performed through the Inter-Device Driver (IDC) DDCMD messages. The MMPM/2 subsystem invokes the VCAI_PLAY functions from one of two places:

�For compressed playback, the hardware (COmpressor/DECompressor) CODEC calls the play function directly with the compressed data.

With compressed data playback, the MCD issues all the VSD/PDD commands except the VCAI_PLAY and VCAI_LOAD_MICROCODE commands-which are issued by the CODEC.

�In the case of uncompressed playback, the play function is issued by the Direct Interface Video Extensions (DIVE) component after the appropriate CODEC has decompressed the image. DIVE knows to call this video device driver instead of the normal display driver because of the [ OverlayAccelerator] entry in the DIVE.INI file, where the VSD DLL (VSDDRIVE =) and video device driver (PDDNAME=) names are specified for DIVE. When DIVE uses the VSD/PDD to play back video, the MCD is unaware of the hardware; DIVE issues all of the VSD/PDD commands to control window placement and playback function.





=== User-Defined Video IOCtls ===

The video IOCtls listed in the following table are category 140 (user defined).

<pre class="western">/----------------------------------------------------------------\
|Function      |Function             |Description                |
|Number        |                     |                           |
|--------------+---------------------+---------------------------|
|60h           |VCAI_INIINFO         |Setup Information          |
|--------------+---------------------+---------------------------|
|61h           |VCAI_SAVE            |Save Device State          |
|--------------+---------------------+---------------------------|
|62h           |VCAI_RESTORE         |Restore Device State       |
|--------------+---------------------+---------------------------|
|63h           |VCAI_LOAD_MICROCODE  |Query/Load/Unload Microcode|
|--------------+---------------------+---------------------------|
|64h           |VCAI_RESTORE_FORMAT  |Set/Query Image Restore    |
|              |                     |Format                     |
|--------------+---------------------+---------------------------|
|65h           |VCAI_CAPTURE_FORMAT  |Set/Query Image Capture    |
|              |                     |Format                     |
|--------------+---------------------+---------------------------|
|67h           |VCAI_PLAY            |Restore Image to the Device|
|--------------+---------------------+---------------------------|
|68h           |VCAI_QUERYVIDEOSIGNAL|Query Video Input          |
|              |                     |Connector's Signal         |
|--------------+---------------------+---------------------------|
|69h           |VCAI_TUNERCHANNEL    |Set/Query Tuner Channel    |
|--------------+---------------------+---------------------------|
|6Ah           |VCAI_VIDEOINPUT      |Set/Query Video Input      |
|              |                     |Source Connector           |
|--------------+---------------------+---------------------------|
|6Bh           |VCAI_SETCAPTRECT     |Set Source and Destination |
|              |                     |Capture Rectangles         |
|--------------+---------------------+---------------------------|
|6Ch           |VCAI_GETIMAGESCALE   |Get Image and Scale into   |
|              |                     |RAM Buffer                 |
|--------------+---------------------+---------------------------|
|6Dh           |VCAI_GETDEVINFO      |Get Device Information     |
|--------------+---------------------+---------------------------|
|6Eh           |VCAI_VALIDRECT       |Validate Video Rectangle   |
|--------------+---------------------+---------------------------|
|72h           |VCAI_UNFREEZE        |Unfreeze Image Digitizer   |
|--------------+---------------------+---------------------------|
|74h           |VCAI_FREEZE          |Freeze Image Digitizer     |
|--------------+---------------------+---------------------------|
|75h           |VCAI_VIDEOADJ        |Set/Query Video Adjustments|
|--------------+---------------------+---------------------------|
|76h           |VCAI_SETFPS          |Set Frame Rate for         |
|              |                     |Streaming                  |
|--------------+---------------------+---------------------------|
|79h           |VCAI_USER            |Device Specific Commands   |
|--------------+---------------------+---------------------------|
|80h           |VCAI_SETMONITOR      |Enable/Disable Overlay     |
|              |                     |Monitor Function           |
|--------------+---------------------+---------------------------|
|81h           |VCAI_EDCOLORKEY      |Enable/Disable Transparent |
|              |                     |Color                      |
|--------------+---------------------+---------------------------|
|82h           |VCAI_SETCOLORKEY     |Set Color Key/Transparent  |
|              |                     |Color                      |
\----------------------------------------------------------------/</pre>
'''Note:'''Functions 68h, 69h, 80h, 81h, and 82h provide support for overlay devices.





=== VCAI_INIINFO (60h) - Setup Information from INI file ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_INIINFO (60h) <br />'''Description:'''<br />Setup Information from INI file

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl provides the device driver with the data from the device driver' s INI file. The name of this file is based on the device driver installation name. For example, the INI file for the first VCA adapter would be VIDVCI1.INI and the second would be VIDVCI2.INI. The VSD reads the INI file and passes information to the PDD as a part of the open processing . The PDDName is obtained from the digital-video device's

<pre class="western">PDDNAME=</pre>
line in the MMPM2.INI file.





=== VCAI_INIINFO (60h) - Description ===

This IOCtl provides the device driver with the data from the device driver' s INI file. The name of this file is based on the device driver installation name. For example, the INI file for the first VCA adapter would be VIDVCI1.INI and the second would be VIDVCI2.INI. The VSD reads the INI file and passes information to the PDD as a part of the open processing . The PDDName is obtained from the digital-video device's

<pre class="western">PDDNAME=</pre>
line in the MMPM2.INI file.





=== VCAI_INIINFO (60h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_INIINFO (60h) - Data Packet Format ===

The data packet parameter is a pointer to device-specific structure.





=== VCAI_INIINFO (60h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_INIINFO (60h) <br />'''Description:'''<br />Setup Information from INI file

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_SAVE (61h) - Save Device State ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SAVE (61h) <br />'''Description:'''<br />Save Device State

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl saves the current state of the video device. The video device can be shared among several processes that might gain or lose ''ownership''of the device at any time. This IOCtl is issued when a process is about to lose ownership of the device and needs to save the state of the device before relinquishing ownership.





=== VCAI_SAVE (61h) - Description ===

This IOCtl saves the current state of the video device. The video device can be shared among several processes that might gain or lose ''ownership''of the device at any time. This IOCtl is issued when a process is about to lose ownership of the device and needs to save the state of the device before relinquishing ownership.





=== VCAI_SAVE (61h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_SAVE (61h) - Data Packet Format ===

Not used.





=== VCAI_SAVE (61h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SAVE (61h) <br />'''Description:'''<br />Save Device State

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_RESTORE (62h) - Restore Device State ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_RESTORE (62h) <br />'''Description:'''<br />Restore Device State

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl restores a previously saved state to the video capture device. This call is issued when a process that owned (but relinquished) the video device is regaining control of the device. The device is set to the state it was in the last time the process was active (save device state was issued), or if the device was not previously active, the device is set to the defaults.





=== VCAI_RESTORE (62h) - Description ===

This IOCtl restores a previously saved state to the video capture device. This call is issued when a process that owned (but relinquished) the video device is regaining control of the device. The device is set to the state it was in the last time the process was active (save device state was issued), or if the device was not previously active, the device is set to the defaults.





=== VCAI_RESTORE (62h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_RESTORE (62h) - Data Packet Format ===

Not used.





=== VCAI_RESTORE (62h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_RESTORE (62h) <br />'''Description:'''<br />Restore Device State

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_LOAD_MICROCODE (63h) - Query/Load/Unload Microcode ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_LOAD_MICROCODE (63h) <br />'''Description:'''<br />Query/Load/Unload Microcode

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl allows the device to be loaded with micro code, if needed. As soon as the current image format is set via [[00635.htm|VCAI_RESTORE_FORMAT]]and/or [[00641.htm|VCAI _CAPTURE_FORMAT]], the device may require micro code to be loaded onto the card. The command allows the micro code's file name to be queried and the micro code to be loaded and later unloaded, if needed. The CODEC (Ring 3 code) will read in the file for the DD (Ring 0 code) because Ring 0 code cannot perform file I/O.





=== VCAI_LOAD_MICROCODE (63h) - Description ===

This IOCtl allows the device to be loaded with micro code, if needed. As soon as the current image format is set via [[00635.htm|VCAI_RESTORE_FORMAT]]and/or [[00641.htm|VCAI _CAPTURE_FORMAT]], the device may require micro code to be loaded onto the card. The command allows the micro code's file name to be queried and the micro code to be loaded and later unloaded, if needed. The CODEC (Ring 3 code) will read in the file for the DD (Ring 0 code) because Ring 0 code cannot perform file I/O.





=== VCAI_LOAD_MICROCODE (63h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_LOAD_MICROCODE (63h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _VCALOAD {
  ULONG       ulflags;
  CHAR        ProdInfo[256];
  LONG        ulLoadID;
  ULONG       ulLength;
  PVOID       pLoadData;
} VCALOAD;

typedef   VCALOAD   FAR   *   PVCALOAD ; </pre>






=== VCAI_LOAD_MICROCODE (63h) - Data Packet Format ===



<pre class="western">/-------------------------------------\
|Field                    C Datatype  |
|-------------------------------------|
|Pointer to structure     PVCALOAD    |
\-------------------------------------/</pre>




=== VCAI_LOAD_MICROCODE (63h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_LOAD_MICROCODE (63h) <br />'''Description:'''<br />Query/Load/Unload Microcode

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_RESTORE_FORMAT (64h) - Query/Set Image Restore Format ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_RESTORE_FORMAT (64h) <br />'''Description:'''<br />Query/Set Image Restore Format

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl is used to query the image formats supported by the device and to query the current image format. It may also be used to set the current image format.

'''Note:'''Image format (fourCC) refers to the type of data that will be passed to the device on the [[00647.htm|VCAI_PLAY]]IOCtl.





=== VCAI_RESTORE_FORMAT (64h) - Description ===

This IOCtl is used to query the image formats supported by the device and to query the current image format. It may also be used to set the current image format.

'''Note:'''Image format (fourCC) refers to the type of data that will be passed to the device on the [[00647.htm|VCAI_PLAY]]IOCtl.





=== VCAI_RESTORE_FORMAT (64h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_RESTORE_FORMAT (64h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _VCAIMAGERF {
  ULONG       ulFlags;
  ULONG       ulNumFormats;
  ULONG       ulCurIndex;
  ULONG       FourCC[64];
} VCAIMAGERF;

typedef   VCAIMAGERF   FAR   *   PVCAIMAGERF ; </pre>






=== VCAI_RESTORE_FORMAT (64h) - Data Packet Format ===



<pre class="western">/----------------------------------------\
|Field                    C Datatype     |
|----------------------------------------|
|Pointer to structure     PVCAIMAGERF    |
\----------------------------------------/</pre>




=== VCAI_RESTORE_FORMAT (64h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_RESTORE_FORMAT (64h) <br />'''Description:'''<br />Query/Set Image Restore Format

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_CAPTURE_FORMAT (65h) - Query/Set Image Capture Format ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_CAPTURE_FORMAT (65h) <br />'''Description:'''<br />Query/Set Image Capture Format

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl is used to query the devices supported image capture formats, query the current image capture format, and set the current image capture format. This image format will be returned on [[00678.htm|VCAI_GETIMAGESCALE]]and on the SHD_READ_COMPLETE flag (of the ''ulFlag''parameter of the [[00966.htm|SHD_REPORTINT]]structure) through the IDC streaming interface.





=== VCAI_CAPTURE_FORMAT (65h) - Description ===

This IOCtl is used to query the devices supported image capture formats, query the current image capture format, and set the current image capture format. This image format will be returned on [[00678.htm|VCAI_GETIMAGESCALE]]and on the SHD_READ_COMPLETE flag (of the ''ulFlag''parameter of the [[00966.htm|SHD_REPORTINT]]structure) through the IDC streaming interface.





=== VCAI_CAPTURE_FORMAT (65h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_CAPTURE_FORMAT (65h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _VCAIMAGECF {
  ULONG       ulFlags;
  ULONG       ulNumFormats;
  ULONG       ulCurIndex;
  ULONG       FourCC[64];
} VCAIMAGECF;

typedef   VCAIMAGECF   FAR   *   PVCAIMAGECF ; </pre>






=== VCAI_CAPTURE_FORMAT (65h) - Data Packet Format ===



<pre class="western">/----------------------------------------\
|Field                    C Datatype     |
|----------------------------------------|
|Pointer to structure     PVCAIMAGECF    |
\----------------------------------------/</pre>




=== VCAI_CAPTURE_FORMAT (65h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_CAPTURE_FORMAT (65h) <br />'''Description:'''<br />Query/Set Image Capture Format

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_PLAY (67h) - Restore/Play Image to the Screen ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_PLAY (67h) <br />'''Description:'''<br />Restore/Play Image to the Screen

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl is used to play back and restore images to a device. The format of the image data pointed to by ''pImageData''is determined by the [[00635.htm|VCAI_ RESTORE_FORMAT]]IOCtl and the source and destination image size is determined by the [[00672.htm|VCAI_SETCAPTRECT]]If the device supports this command, the ''CanRestore''flag in the [[01006.htm|VCADEVINFO]]structure should be set to 1.





=== VCAI_PLAY (67h) - Description ===

This IOCtl is used to play back and restore images to a device. The format of the image data pointed to by ''pImageData''is determined by the [[00635.htm|VCAI_ RESTORE_FORMAT]]IOCtl and the source and destination image size is determined by the [[00672.htm|VCAI_SETCAPTRECT]]If the device supports this command, the ''CanRestore''flag in the [[01006.htm|VCADEVINFO]]structure should be set to 1.





=== VCAI_PLAY (67h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_PLAY (67h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCASTREAM {
  ULONG       ulLength;
  PVOID       pImageData;
  ULONG       ulFlags;
  ULONG       ulSCR;
  ULONG       ulPTS;
  ULONG       ulAudioTime;
} VCASTREAM;

typedef   VCASTREAM   FAR   *   PVCASTREAM ; </pre>






=== VCAI_PLAY (67h) - Data Packet Format ===



<pre class="western">/---------------------------------------\
|Field                    C Datatype    |
|---------------------------------------|
|Pointer to structure     PVCASTREAM    |
\---------------------------------------/</pre>




=== VCAI_PLAY (67h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_PLAY (67h) <br />'''Description:'''<br />Restore/Play Image to the Screen

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_QUERYVIDEOSIGNAL (68h) - Query Video Input Connector's Signal ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_QUERYVIDEOSIGNAL (68h) <br />'''Description:'''<br />Query Video Input Connector's Signal

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>

-----

This IOCtl is used to determine if the current video input connector has a valid video signal present. For example, this IOCtl could be used to help automatically detect which video input has a camera attached and turned on or whether or not the tuner is tuned to a valid channel.





=== VCAI_QUERYVIDEOSIGNAL (68h) - Description ===

This IOCtl is used to determine if the current video input connector has a valid video signal present. For example, this IOCtl could be used to help automatically detect which video input has a camera attached and turned on or whether or not the tuner is tuned to a valid channel.





=== VCAI_QUERYVIDEOSIGNAL (68h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_QUERYVIDEOSIGNAL (68h) - Data Packet Format ===

Not used.





=== VCAI_QUERYVIDEOSIGNAL (68h) - Returns ===

This IOCtl returns a status value equal to one of the following.

<pre class="western">VCAERR_SIGNAL_LOCKED          10
VCAERR_SIGNAL_NOT_LOCKED      11
VCAERR_SIGNAL_INDETERMINATE   12</pre>




=== VCAI_QUERYVIDEOSIGNAL (68h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_QUERYVIDEOSIGNAL (68h) <br />'''Description:'''<br />Query Video Input Connector's Signal

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>




=== VCAI_TUNERCHANNEL (69h) - Set/Query Tuner Channel ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_TUNERCHANNEL (69h) <br />'''Description:'''<br />Set/Query Tuner Channel

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>

-----

This IOCtl is used to change channel/frequency on the TV tuner or to query the correct tuner frequency. If the device support TV tuner functions, the ''HasTuner''flag should be set to 1 in the [[01006.htm|VCADEVINFO]]structure.





=== VCAI_TUNERCHANNEL (69h) - Description ===

This IOCtl is used to change channel/frequency on the TV tuner or to query the correct tuner frequency. If the device support TV tuner functions, the ''HasTuner''flag should be set to 1 in the [[01006.htm|VCADEVINFO]]structure.





=== VCAI_TUNERCHANNEL (69h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_TUNERCHANNEL (69h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCATUNCHAN {
  ULONG        ulFlags;
  ULONG        ulOptions;
  USHORT       usResv01;
  USHORT       usResv02;
  LONG         lFineTune;
  ULONG        ulFrequency;
} VCATUNCHAN;

typedef   VCATUNCHAN   FAR   *   PVCATUNCHAN ; </pre>






=== VCAI_TUNERCHANNEL (69h) - Data Packet Format ===



<pre class="western">/----------------------------------------\
|Field                    C Datatype     |
|----------------------------------------|
|Pointer to structure     PVCATUNCHAN    |
\----------------------------------------/</pre>




=== VCAI_TUNERCHANNEL (69h) - Returns ===

The following status values are returned by VCAI_TUNERCHANNEL.

<pre class="western">VCAERR_CHANNEL_TOO_LOW     6
VCAERR_CHANNEL_TOO_HIGH    7
VCAERR_CHANNEL_NO_TUNER    9</pre>




=== VCAI_TUNERCHANNEL (69h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_TUNERCHANNEL (69h) <br />'''Description:'''<br />Set/Query Tuner Channel

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns </pre>




=== VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_VIDEOINPUT (6Ah) <br />'''Description:'''<br />Set/Query Video Input Source Connector

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl sets or queries the current video input source connector.





=== VCAI_VIDEOINPUT (6Ah) - Description ===

This IOCtl sets or queries the current video input source connector.





=== VCAI_VIDEOINPUT (6Ah) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_VIDEOINPUT (6Ah) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _VCASETVIDEOINPUT {
  ULONG       INPUT_CONNECTOR;
} VCASETVIDEOINPUT;

typedef   VCASETVIDEOINPUT   FAR   *   PVCASETVIDEOINPUT ; </pre>






=== VCAI_VIDEOINPUT (6Ah) - Data Packet Format ===



<pre class="western">/----------------------------------------------\
|Field                    C Datatype           |
|----------------------------------------------|
|Pointer to structure     PVCASETVIDEOINPUT    |
\----------------------------------------------/</pre>




=== VCAI_VIDEOINPUT (6Ah) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_VIDEOINPUT (6Ah) <br />'''Description:'''<br />Set/Query Video Input Source Connector

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_SETCAPTRECT (6Bh) - Set Source and Destination Capture/Restore Rectangles ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETCAPTRECT (6Bh) <br />'''Description:'''<br />Set Source and Destination Capture/Restore Rectangles

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl sets up streaming capture of images from the video capture device to buffers provided by the [[00176.htm|DDCMD_READ]]message. The portion of the source image to be captured is determined by the size of the destination image.

This command does not start the capture. It specifies the source and destination. Streaming capture is started using the DDCMD_START flag of the ''ulCmd''parameter of the [[00759.htm|DDCMDCONTROL]]structure.

The destination X_LEFT and Y_TOP are used only for overlay adapters to control where the overlay image is placed on the screen.

If the device is being used for play back instead of capture as discussed above, ''source''refers to the size of the image that is to be restored and ''dest''(destination) refers to where the image is to be placed. Instead of the DDCMD message discussed above, the image data is passed to the device driver via the [[00647.htm|VCAI_PLAY]]IOCtl.





=== VCAI_SETCAPTRECT (6Bh) - Description ===

This IOCtl sets up streaming capture of images from the video capture device to buffers provided by the [[00176.htm|DDCMD_READ]]message. The portion of the source image to be captured is determined by the size of the destination image.

This command does not start the capture. It specifies the source and destination. Streaming capture is started using the DDCMD_START flag of the ''ulCmd''parameter of the [[00759.htm|DDCMDCONTROL]]structure.

The destination X_LEFT and Y_TOP are used only for overlay adapters to control where the overlay image is placed on the screen.

If the device is being used for play back instead of capture as discussed above, ''source''refers to the size of the image that is to be restored and ''dest''(destination) refers to where the image is to be placed. Instead of the DDCMD message discussed above, the image data is passed to the device driver via the [[00647.htm|VCAI_PLAY]]IOCtl.





=== VCAI_SETCAPTRECT (6Bh) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_SETCAPTRECT (6Bh) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _VCASETCAPTURERECT {
  ULONG       Source_X_Left;
  ULONG       Source_Y_Top;
  ULONG       Source_Y_Height;
  ULONG       Source_X_Width;
  ULONG       Dest_X_Left;
  ULONG       Dest_Y_Top;
  ULONG       Dest_Y_Height;
  ULONG       Dest_X_Width;
} VCASETCAPTURERECT;

typedef   VCASETCAPTURERECT   FAR   *   PVCASETCAPTURERECT ; </pre>






=== VCAI_SETCAPTRECT (6Bh) - Data Packet Format ===



<pre class="western">/-----------------------------------------------\
|Field                    C Datatype            |
|-----------------------------------------------|
|Pointer to structure     PVCASETCAPTURERECT    |
\-----------------------------------------------/</pre>




=== VCAI_SETCAPTRECT (6Bh) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETCAPTRECT (6Bh) <br />'''Description:'''<br />Set Source and Destination Capture/Restore Rectangles

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_GETIMAGESCALE (6Ch) - Get Image and Scale into RAM Buffer ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_GETIMAGESCALE (6Ch) <br />'''Description:'''<br />Get Image and Scale into RAM Buffer

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>

-----

This IOCtl is used to capture a single frame of data from the video capture device to a buffer provided by the calling application.

The video capture device has a capture frame buffer, which contains the current, full sized image captured (or ''digitized'') by the device. The portion of the full sized image that is to be copied to the calling applications buffer is indicated by the source frame, which describes a window in the captured frame. The source frame can encompass part or all of the captured frame. The image data contained in the source frame dimensions are copied to a destination frame. The following figure illustrates this.

<pre class="western">        0,0                       0,0
        /--------------------\    /--------------------\
        |   64               |    |                    |
   32   |  /-------------\   |    |                    |
        |  |Source   240 | --+---&gt;|  Destination       |
        |  |             |   |    |                    |
        |  |   320       |   |    |                    |
        |  \-------------/   |    |                    |
        \--------------------/    \--------------------/
                    640,480                      160,120

  X-Left    32
  Y-Top     64
  X-Width  320
  Y-Height 240</pre>
If the destination frame is not the same size as the source frame, the source image is scaled down to fit into the destination frame. This allows the image to be reduced to fit in a specific window. It also allows for a change in the aspect ratio.

For better performance, this IOCtl does not validate that the source and destination frames are equal to or smaller than the full sized capture frame. The caller of this function ''must''ensure that the source and destination frame dimensions are less than or equal to the maximum size of the capture frame. Use [[00686.htm|VCAI_GETDEVINFO]]to determine the maximum image extents.

Specific device drivers might place restrictions on how scaling from the source frame to the destination frame can occur.





=== VCAI_GETIMAGESCALE (6Ch) - Description ===

This IOCtl is used to capture a single frame of data from the video capture device to a buffer provided by the calling application.

The video capture device has a capture frame buffer, which contains the current, full sized image captured (or ''digitized'') by the device. The portion of the full sized image that is to be copied to the calling applications buffer is indicated by the source frame, which describes a window in the captured frame. The source frame can encompass part or all of the captured frame. The image data contained in the source frame dimensions are copied to a destination frame. The following figure illustrates this.

<pre class="western">        0,0                       0,0
        /--------------------\    /--------------------\
        |   64               |    |                    |
   32   |  /-------------\   |    |                    |
        |  |Source   240 | --+---&gt;|  Destination       |
        |  |             |   |    |                    |
        |  |   320       |   |    |                    |
        |  \-------------/   |    |                    |
        \--------------------/    \--------------------/
                    640,480                      160,120

  X-Left    32
  Y-Top     64
  X-Width  320
  Y-Height 240</pre>
If the destination frame is not the same size as the source frame, the source image is scaled down to fit into the destination frame. This allows the image to be reduced to fit in a specific window. It also allows for a change in the aspect ratio.

For better performance, this IOCtl does not validate that the source and destination frames are equal to or smaller than the full sized capture frame. The caller of this function ''must''ensure that the source and destination frame dimensions are less than or equal to the maximum size of the capture frame. Use [[00686.htm|VCAI_GETDEVINFO]]to determine the maximum image extents.

Specific device drivers might place restrictions on how scaling from the source frame to the destination frame can occur.





=== VCAI_GETIMAGESCALE (6Ch) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_GETIMAGESCALE (6Ch) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCAGETIMAGESCALE {
  ULONG       Capture_Buf_Len;
  ULONG       Capture_Buf_Ptr;
  ULONG       Source_X_Left;
  ULONG       Source_Y_Top;
  ULONG       Source_Y_Height;
  ULONG       Source_X_Width;
  ULONG       Dest_X_Left;
  ULONG       Dest_Y_Top;
  ULONG       Dest_Y_Height;
  ULONG       Dest_X_Width;
} VCAGETIMAGESCALE;

typedef   VCAGETIMAGESCLAE   FAR   *   PVCAGETIMAGESCALE ; </pre>






=== VCAI_GETIMAGESCALE (6Ch) - Data Packet Format ===



<pre class="western">/----------------------------------------------\
|Field                    C Datatype           |
|----------------------------------------------|
|Pointer to structure     PVCAGETIMAGESCALE    |
\----------------------------------------------/</pre>




=== VCAI_GETIMAGESCALE (6Ch) - Returns ===

If the video device driver can satisfy the request as specified, it returns 0 (VCAERR_SUCCESS). Otherwise, an error code is returned that indicates what caused the failure (VCAERR_INVALID_BUFFER, VCAERR_INVALID_RECT).





=== VCAI_GETIMAGESCALE (6Ch) - Remarks ===

This IOCtl captures one single video image per call. To perform streaming ( continuous, multiple image capturing), use the stream programming interface to create a stream and record from the video capture device.

'''Note:'''Most video device drivers ''do not''support all the transposition and scaling possibilities supported with this IOCtl. Consult the specific device driver's documentation for limitations, or use [[00686.htm|VCAI_GETDEVINFO]]to determine its capabilities.





=== VCAI_GETIMAGESCALE (6Ch) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_GETIMAGESCALE (6Ch) <br />'''Description:'''<br />Get Image and Scale into RAM Buffer

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Returns 
Remarks </pre>




=== VCAI_GETDEVINFO (6Dh) - Get Device Information ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_GETDEVINFO (6Dh) <br />'''Description:'''<br />Get Device Information

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl returns device-specific information about a video capture device . The information returned is the default state of the device. It does not reflect changes that might have been made to the defaults since initialization.





=== VCAI_GETDEVINFO (6Dh) - Description ===

This IOCtl returns device-specific information about a video capture device . The information returned is the default state of the device. It does not reflect changes that might have been made to the defaults since initialization.





=== VCAI_GETDEVINFO (6Dh) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_GETDEVINFO (6Dh) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following data structure.

<pre class="western">typedef struct _vcadevinfo {
  ULONG        Length;
  CHAR         ProdInfo[30];
  CHAR         ManInfo[30];
  CHAR         Version[10];
  ULONG        ImgFormat;
  USHORT       BitsPerPEL;
  USHORT       Overlay;
  ULONG        Brightness;
  ULONG        hue;
  ULONG        saturation;
  ULONG        contrast;
  ULONG        Sharpness;
  ULONG        unused1;
  ULONG        S_X_Left;
  ULONG        S_Y_Top;
  ULONG        S_Y_Height;
  ULONG        S_X_Width;
  ULONG        D_X_Left;
  ULONG        D_Y_Top;
  ULONG        D_Y_Height;
  ULONG        D_X_Width;
  ULONG        D_ScaleFactor;
  ULONG        S_X_MAX;
  ULONG        S_Y_MAX;
  ULONG        D_X_MAX;
  ULONG        D_Y_MAX;
  ULONG        O_X_MAX;
  ULONG        O_Y_MAX;
  USHORT       VideoInputs;
  USHORT       CanRestore;
  USHORT       CanStretch;
  USHORT       CanDistort;
  USHORT       HasVolume;
  USHORT       HasBalance;
  USHORT       CanScale;
  USHORT       CanStream;
  ULONG        DI_ulFilenum;
  BYTE         HasTuner;
  BYTE         HasTeleTex;
  LONG         Delay_Time;
  BYTE         HasAFC;
  BYTE         HasPolarization;
} VCADEVINFO;

typedef   VCADEVINFO   FAR   *   PVCADEVINFO ; </pre>






=== VCAI_GETDEVINFO (6Dh) - Data Packet Format ===



<pre class="western">/----------------------------------------\
|Field                    C Datatype     |
|----------------------------------------|
|Pointer to structure     PVCADEVINFO    |
\----------------------------------------/</pre>




=== VCAI_GETDEVINFO (6Dh) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_GETDEVINFO (6Dh) <br />'''Description:'''<br />Get Device Information

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_VALIDRECT (6Eh) - Validate Video Rectangle ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_VALIDRECT (6Eh) <br />'''Description:'''<br />Validate Video Rectangle

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl modifies the source ''X_Width''and source ''Y_Height''to a valid size determined by the destination rectangle information. This IOCtl compensates for video capture adapters that do not support scaling images from a given source destination rectangle. The media control driver uses this information to center the source rectangle on the area in the original source rectangle.





=== VCAI_VALIDRECT (6Eh) - Description ===

This IOCtl modifies the source ''X_Width''and source ''Y_Height''to a valid size determined by the destination rectangle information. This IOCtl compensates for video capture adapters that do not support scaling images from a given source destination rectangle. The media control driver uses this information to center the source rectangle on the area in the original source rectangle.





=== VCAI_VALIDRECT (6Eh) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_VALIDRECT (6Eh) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCACAPISIZE {
  ULONG       X_Left;
  ULONG       Y_Top;
  ULONG       Y_Height;
  ULONG       X_Width;
  ULONG       ScaleFactor;
} VCACAPISIZE;

typedef   VCACAPISIZE   FAR   *   PVCACAPISIZE ; </pre>






=== VCAI_VALIDRECT (6Eh) - Data Packet Format ===



<pre class="western">/-----------------------------------------\
|Field                    C Datatype      |
|-----------------------------------------|
|Pointer to structure     PVCACAPISIZE    |
\-----------------------------------------/</pre>




=== VCAI_VALIDRECT (6Eh) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_VALIDRECT (6Eh) <br />'''Description:'''<br />Validate Video Rectangle

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_UNFREEZE (72h) <br />'''Description:'''<br />Unfreeze the Image Digitizer

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl tells the video device to continuously digitize the incoming video source.





=== VCAI_UNFREEZE (72h) - Description ===

This IOCtl tells the video device to continuously digitize the incoming video source.





=== VCAI_UNFREEZE (72h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_UNFREEZE (72h) - Data Packet Format ===

Not used.





=== VCAI_UNFREEZE (72h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_UNFREEZE (72h) <br />'''Description:'''<br />Unfreeze the Image Digitizer

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_FREEZE (74h) - Freeze the Image Digitizer ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_FREEZE (74h) <br />'''Description:'''<br />Freeze the Image Digitizer

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl tells the video device to freeze the current digitized image. This freezes the capture card digitizer to produce a stable image. However, it is typically very slow because the device might have to wait for one or more video field times to pass to make sure the digitizer has come to a complete stop.





=== VCAI_FREEZE (74h) - Description ===

This IOCtl tells the video device to freeze the current digitized image. This freezes the capture card digitizer to produce a stable image. However, it is typically very slow because the device might have to wait for one or more video field times to pass to make sure the digitizer has come to a complete stop.





=== VCAI_FREEZE (74h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_FREEZE (74h) - Data Packet Format ===

Not used.





=== VCAI_FREEZE (74h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_FREEZE (74h) <br />'''Description:'''<br />Freeze the Image Digitizer

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_VIDEOADJ (75h) - Set/Query Video Adjustments ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_VIDEOADJ (75h) <br />'''Description:'''<br />Set/Query Video Adjustments

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Remarks </pre>

-----

This IOCtl allows the caller to set and query the value of attributes controlling the behavior (and thus the image) of the video device. Typical video image adjustments, such as those found on television sets, including brightness, contrast, and hue, can be queried and set with this call.





=== VCAI_VIDEOADJ (75h) - Description ===

This IOCtl allows the caller to set and query the value of attributes controlling the behavior (and thus the image) of the video device. Typical video image adjustments, such as those found on television sets, including brightness, contrast, and hue, can be queried and set with this call.





=== VCAI_VIDEOADJ (75h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_VIDEOADJ (75h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCASETVIDEO {
  ULONG       set_brightness;
  ULONG       set_hue;
  ULONG       set_saturation;
  ULONG       set_contrast;
  ULONG       ret_brightness;
  ULONG       ret_hue;
  ULONG       ret_saturation;
  ULONG       ret_contrast;
} VCASETVIDEO;

typedef   VCASETVIDEO   FAR   *   PVCASETVIDEO ; </pre>






=== VCAI_VIDEOADJ (75h) - Data Packet Format ===



<pre class="western">/-----------------------------------------\
|Field                    C Datatype      |
|-----------------------------------------|
|Pointer to structure     PVCASETVIDEO    |
\-----------------------------------------/</pre>




=== VCAI_VIDEOADJ (75h) - Remarks ===

When setting a value, put the value desired (in the range of 0 to 255) into the value's field. If resetting the value to the defaults, put DEFAULT into the value's field. If no change is desired for a particular value, put NO_ CHANGE in the value's field. The call always returns the current value or NOT_SUPPORTED for each setting after the value has been updated.





=== VCAI_VIDEOADJ (75h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_VIDEOADJ (75h) <br />'''Description:'''<br />Set/Query Video Adjustments

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format 
Remarks </pre>




=== VCAI_SETFPS (76h) - Set Frame Rate for Streaming ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETFPS (76h) <br />'''Description:'''<br />Set Frame Rate for Streaming

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl allows the caller to set the frame rate, in frames per second or in microseconds per frame, that the device driver will use to capture images from the device. This call does not initiate video capture, it only sets the frame rate. The frame rate ''cannot''





=== VCAI_SETFPS (76h) - Description ===

This IOCtl allows the caller to set the frame rate, in frames per second or in microseconds per frame, that the device driver will use to capture images from the device. This call does not initiate video capture, it only sets the frame rate. The frame rate ''cannot''





=== VCAI_SETFPS (76h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_SETFPS (76h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCASETFPS {
  ULONG       set_FPS;
  ULONG       ulFlags;
} VCASETFPS;

typedef   VCASETFPS   FAR   *   PVCASETFPS ; </pre>






=== VCAI_SETFPS (76h) - Data Packet Format ===



<pre class="western">/---------------------------------------\
|Field                    C Datatype    |
|---------------------------------------|
|Pointer to structure     PVCASETFPS    |
\---------------------------------------/</pre>




=== VCAI_SETFPS (76h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETFPS (76h) <br />'''Description:'''<br />Set Frame Rate for Streaming

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_USER (79h) - Pass Device-Specific Commands to Device Driver ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_USER (79h) <br />'''Description:'''<br />Pass Device-Specific Commands to Device Driver

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl is the result of a MCI_DEV_ESCAPE COMMAND. It allows an application to pass device-specific commands to the device driver. This will allow for new commands specific to a device to be supported without impact to the MCD/MCI.





=== VCAI_USER (79h) - Description ===

This IOCtl is the result of a MCI_DEV_ESCAPE COMMAND. It allows an application to pass device-specific commands to the device driver. This will allow for new commands specific to a device to be supported without impact to the MCD/MCI.





=== VCAI_USER (79h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_USER (79h) - Data Packet Format ===

Application Dependent.





=== VCAI_USER (79h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_USER (79h) <br />'''Description:'''<br />Pass Device-Specific Commands to Device Driver

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETMONITOR (80h) <br />'''Description:'''<br />Enable/Disable Overlay Monitor

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl enables or disables display of live video on the display device.





=== VCAI_SETMONITOR (80h) - Description ===

This IOCtl enables or disables display of live video on the display device.





=== VCAI_SETMONITOR (80h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_SETMONITOR (80h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCASETMONITOR {
  BOOL       bMonitor;
} VCASETMONITOR;

typedef   VCASETMONITOR   FAR   *   PVCASETMONITOR ; </pre>






=== VCAI_SETMONITOR (80h) - Data Packet Format ===



<pre class="western">/-------------------------------------------\
|Field                    C Datatype        |
|-------------------------------------------|
|Pointer to structure     PVCASETMONITOR    |
\-------------------------------------------/</pre>




=== VCAI_SETMONITOR (80h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETMONITOR (80h) <br />'''Description:'''<br />Enable/Disable Overlay Monitor

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_EDCOLORKEY (81h) - Enable/Disable Transparent Color ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_EDCOLORKEY (81h) <br />'''Description:'''<br />Enable/Disable Transparent Color

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl enables video to show through a specific color determined by the transparent-color key when the overlay monitor is enabled. If color keying is not enabled and the monitor is enabled, video will show through even if the transparent color is not present.





=== VCAI_EDCOLORKEY (81h) - Description ===

This IOCtl enables video to show through a specific color determined by the transparent-color key when the overlay monitor is enabled. If color keying is not enabled and the monitor is enabled, video will show through even if the transparent color is not present.





=== VCAI_EDCOLORKEY (81h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_EDCOLORKEY (81h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCAEDCOLORKEY {
  BOOL       bColorKeying;
} VCAEDCOLORKEY;

typedef   VCAEDCOLORKEY   FAR   *   PVCAEDCOLORKEY ; </pre>






=== VCAI_EDCOLORKEY (81h) - Data Packet Format ===



<pre class="western">/-------------------------------------------\
|Field                    C Datatype        |
|-------------------------------------------|
|Pointer to structure     PVCAEDCOLORKEY    |
\-------------------------------------------/</pre>




=== VCAI_EDCOLORKEY (81h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_EDCOLORKEY (81h) <br />'''Description:'''<br />Enable/Disable Transparent Color

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== VCAI_SETCOLORKEY (82h) - Set Color Key/Transparent Color ===


-----

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETCOLORKEY (82h) <br />'''Description:'''<br />Set Color Key/Transparent Color

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>

-----

This IOCtl sets the colors that video replaces when color keying is enabled and the monitor is enabled.





=== VCAI_SETCOLORKEY (82h) - Description ===

This IOCtl sets the colors that video replaces when color keying is enabled and the monitor is enabled.





=== VCAI_SETCOLORKEY (82h) - Parameter Packet Format ===

Not used. The packet pointer must be NULL.





=== VCAI_SETCOLORKEY (82h) - Pointer to structure ===

'''Pointer to structure'''The data packet parameter is a pointer to the following structure.

<pre class="western">typedef struct _VCASETCOLORKEY {
  ULONG       ulColorKey;
} VCASETCOLORKEY;

typedef   VCASETCOLORKEY   FAR   *   PVCASETCOLORKEY ; </pre>






=== VCAI_SETCOLORKEY (82h) - Data Packet Format ===



<pre class="western">/--------------------------------------------\
|Field                    C Datatype         |
|--------------------------------------------|
|Pointer to structure     PVCASETCOLORKEY    |
\--------------------------------------------/</pre>




=== VCAI_SETCOLORKEY (82h) - ===

'''Category:'''<br />VIDEO_IOCTL_CAT (140) <br />'''Function:'''<br />VCAI_SETCOLORKEY (82h) <br />'''Description:'''<br />Set Color Key/Transparent Color

Select an item:

<pre class="western">Description
Parameter Packet Format 
Data Packet Format </pre>




=== Data Types ===

This section describes data types in C language.





=== audio_update ===

This structure contains fields for the [[00550.htm|AUDIO_UPDATE]]IOCtl.

<pre class="western">typedef struct _audio_update {
  CHAR           iobuf_type;      /*  Transmit or receive. */
  CHAR FAR      *buffer_address;  /*  Address of buffer be added. */
  ULONG          buffer_length;   /*  Length of buffer to be added. */
  USHORT         rc;              /*  Return code. */
  void FAR      *reserved;        /*  Reserved. */
} audio_update;

typedef   struct   audio _ update   FAR   * UPDATE ; </pre>




=== audio_update Field - iobuf_type ===

'''iobuf_type'''([[00753.htm|CHAR]]) Transmit or receive ''iobuf''. The defined values for this field are:

<pre class="western">XMIT_IOBUF   0
REC_IOBUF    1</pre>






=== audio_update Field - buffer_address ===

'''buffer_address'''([[00753.htm|CHAR FAR *]]) Address of buffer be added.





=== audio_update Field - buffer_length ===

'''buffer_length'''([[00998.htm|ULONG]]) Length of buffer to be added.





=== audio_update Field - rc ===

'''rc'''([[00999.htm|USHORT]]) Return code. The following values are defined for ''rc''.

<pre class="western">MAX_NUM_BUFFERS_REACHED          9
UPDATE_GENERAL_FAILURE          10
INVALID_BUFFER_LENGTH           11</pre>






=== audio_update Field - reserved ===

'''reserved'''(void FAR *) Reserved.





=== BOOL ===

Boolean.

Valid values are:

�FALSE, which is 0 <br />�TRUE, which is 1

<pre class="western">typedef unsigned long BOOL;</pre>




=== BYTE ===

A byte.

<pre class="western">typedef unsigned char BYTE;</pre>




=== CHAR ===

Single-byte character.

<pre class="western">#define CHAR char</pre>




=== CONTROL_PARM ===

This data structure contains fields for the ''pParm''and ''ulParmSize''fields of the [[00759.htm|DDCMDCONTROL]]data structure.

<pre class="western">typedef struct _CONTROL_PARM {
  ULONG     ulTime;  /*  Time in milliseconds. */
} CONTROL_PARM;
</pre>




=== CONTROL_PARM Field - ulTime ===

'''ulTime'''([[00998.htm|ULONG]]) Specifies the time in milliseconds. The stream handler sets the cue time when the ''ulCmd''field of the [[00759.htm|DDCMDCONTROL]]data structure is DDCMD_ENABLE_EVENT. The PDD returns the current time for DDCMD_STOP and DDCMD_PAUSE.





=== DDCMDCOMMON ===

This data structure contains common fields between all DDCMD data structures.

<pre class="western">typedef struct _ddcmd_common_parm {
  ULONG       ulFunction;  /*  Function requested by stream handler. */
  HSTREAM     hStream;     /*  Data stream instance. */
} DDCMDCOMMON;
</pre>




=== DDCMDCOMMON Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDCOMMON Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the data stream instance for this event.





=== DDCMDCONTROL ===

This data structure contains fields for the [[00162.htm|DDCMD_CONTROL]]message.

<pre class="western">typedef struct _ddcmd_control_parm {
  ULONG       ulFunction;  /*  Function requested. */
  HSTREAM     hStream;     /*  Stream handle. */
  HEVENT      hEvent;      /*  Event handle. */
  ULONG       ulCmd;       /*  Flags. */
  PVOID       pParm;       /*  Pointer to CONTROL_PARM. */
  ULONG       ulParmSize;  /*  See CONTROL_PARM. */
} DDCMDCONTROL;
</pre>




=== DDCMDCONTROL Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDCONTROL Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle that identifies the stream instance for this event.





=== DDCMDCONTROL Field - hEvent ===

'''hEvent'''([[00807.htm|HEVENT]]) Event handle.





=== DDCMDCONTROL Field - ulCmd ===

'''ulCmd'''([[00998.htm|ULONG]]) Defines the following flags:

DDCMD_START Starts a device.

DDCMD_STOP Stops a device and returns the current stream time in milliseconds. All buffers in the PDD are flushed and everything is reset to 0. The device driver sends the current stream time back to the stream handler in milliseconds (using the ''pParm''and ''ulParmSize''fields). For example, return a ULONG of stream time (in milliseconds) and the ULONG of 4 bytes is input in the ''ulParmSize''field.

DDCMD_PAUSE Pauses the device and returns the current stream time in milliseconds. Unlike DDCMD_STOP, DDCMD_PAUSE is not destructive. The device driver is able to resume its function at a later time, exactly where it was paused. DDCMD_ PAUSE returns the current stream time in milliseconds within the ''pParm''field.

DDCMD_RESUME Resumes a currently paused stream. DDCMD_RESUME is only honored if the stream was paused previously. If the stream was stopped and the stream handler issues DDCMD_RESUME, an ERROR_INVALID_SEQUENCE is returned.

DDCMD_ENABLE_EVENT Enables event detection if your PDD supports events. The event message is sent to the device driver and reviews the structure. The ''hEvent''field is a unique handle that signifies the event. ''pParm''contains the stream time with which the event should be detected. This command would be honored whether currently in a streaming state, pause, or stop.

For example, a stream handler is programmed to be detected at 1000 milliseconds in the stream. It sends a DDCMD_ENABLE_EVENT to the device driver with a unique handle event (''hEvent'') and 1000 milliseconds stated in the ''pParm''field. The device driver obtains the handle event, makes sure there are no duplicate entries, and adds the ''hEvent''to a link list or array (depending on how the device driver is implemented). The device driver now knows it must report an event back to the stream handler when 1000 milliseconds has been reached in the stream. See [[00220.htm|SHD_REPORT_EVENT]]for further information.

DDCMD_DISABLE_EVENT Disables event detection in the device driver. An event handle is passed from the structure. The device driver searches its linked list or array to find the matching event handle and deletes it from the list.

DDCMD_PAUSE_TIME Pauses the time but not the stream.

DDCMD_RESUME_TIME Resumes the time.





=== DDCMDCONTROL Field - pParm ===

'''pParm'''([[01203.htm|PVOID]]) Pointer to the [[00754.htm|CONTROL_PARM]]data structure.





=== DDCMDCONTROL Field - ulParmSize ===

'''ulParmSize'''([[00998.htm|ULONG]]) Size of the [[00754.htm|CONTROL_PARM]]data structure.





=== DDCMDDEREGISTER ===

This data structure contains fields for the [[00169.htm|DDCMD_DEREG_STREAM]]message.

<pre class="western">typedef struct _ddcmd_deregister_parm {
  ULONG       ulFunction;  /*  Function requested by stream handler. */
  HSTREAM     hStream;     /*  Stream handle. */
} DDCMDDEREGISTER;
</pre>




=== DDCMDDEREGISTER Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDDEREGISTER Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle needed at interrupt time.





=== DDCMDREADWRITE ===

This data structure contains fields for the [[00176.htm|DDCMD_READ]]and [[00204.htm|DDCMD_WRITE]]messages.

<pre class="western">typedef struct _ddcmd_readwrite_parm {
  ULONG       ulFunction;    /*  Function requested by stream handler. */
  HSTREAM     hStream;       /*  Stream handle. */
  PVOID       pBuffer;       /*  Buffer pointer. */
  ULONG       ulBufferSize;  /*  Buffer size. */
  PVOID       pProcessLin;   /*  Process linear record pointer. */
  BOOL        fEOS;          /*  Whether or not this is the EOS buffer. */
  ULONG       ulParm1;       /*  Reserved for future use. */
  ULONG       ulParm2;       /*  Reserved for future use. */
  ULONG       ulLength;      /*  Length of the structure. */
} DDCMDREADWRITE;
</pre>




=== DDCMDREADWRITE Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDREADWRITE Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle that identifies the stream instance for this event.





=== DDCMDREADWRITE Field - pBuffer ===

'''pBuffer'''([[01203.htm|PVOID]]) Buffer pointer of the empty buffer that the device driver fills from its record operation.





=== DDCMDREADWRITE Field - ulBufferSize ===

'''ulBufferSize'''([[00998.htm|ULONG]]) Specifies the buffer size of the empty buffer.





=== DDCMDREADWRITE Field - pProcessLin ===

'''pProcessLin'''([[01203.htm|PVOID]]) Provides the 32-bit process linear address to a Ring 3 stream handler so the stream handler will have access to the buffers if a GDT or physical address is requested.





=== DDCMDREADWRITE Field - fEOS ===

'''fEOS'''([[00751.htm|BOOL]]) Whether or not this is the EOS buffer.





=== DDCMDREADWRITE Field - ulParm1 ===

'''ulParm1'''([[00998.htm|ULONG]]) For MPEG, contains the initial audio system clock reference (SCR).





=== DDCMDREADWRITE Field - ulParm2 ===

'''ulParm2'''([[00998.htm|ULONG]]) For MPEG, contains the Presentation Time Stamp (PTS).





=== DDCMDREADWRITE Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== DDCMDREGISTER ===

This data structure contains fields for the [[00183.htm|DDCMD_REG_STREAM]]message.

<pre class="western">typedef struct _ddcmd_register_parm {
  ULONG       ulFunction;         /*  Function requested by stream handler. */
  HSTREAM     hStream;            /*  Stream handle. */
  ULONG       ulSysFileNum;       /*  Device handle. */
  PSHDFN      pSHDEntryPoint;     /*  Stream handler entry point. */
  ULONG       ulStreamOperation;  /*  Stream operation. */
  SPCBKEY     spcbkey;            /*  Input to the VSD or PDD (optional) buffer size. */
  ULONG       ulBufSize;          /*  VSD or PDD output buffer size in bytes. */
  ULONG       ulNumBufs;          /*  VSD or PDD output total number of buffers for SPCB. */
  ULONG       ulAddressType;      /*  VSD or PDD output (required) addr ptr type to data buffer. */
  ULONG       ulBytesPerUnit;     /*  VSD or PDD output (unused, set to zero). */
  MMTIME      mmtimePerUnit;      /*  VSD or PDD output (Unused, set to zero). */
  E_DCB       dcbAudio;           /*  Stream handler DCB. */
  HID         hid;                /*  Stream handler ID. */
} DDCMDREGISTER;
</pre>




=== DDCMDREGISTER Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDREGISTER Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle to communicate with the stream handler at interrupt time.





=== DDCMDREGISTER Field - ulSysFileNum ===

'''ulSysFileNum'''([[00998.htm|ULONG]]) Specifies the device handle so the VSD or PDD can map the device instance to ''hStream''. This field has to map with how the device has been initialized during [[00498.htm|AUDIO_INIT]].





=== DDCMDREGISTER Field - pSHDEntryPoint ===

'''pSHDEntryPoint'''([[00953.htm|PSHDFN]]) Specifies the stream handler entry point so that the device driver can call back into the stream handler during streaming time to report interrupts and events. For VSDs this is a user-level stream handler entry point.





=== DDCMDREGISTER Field - ulStreamOperation ===

'''ulStreamOperation'''([[00998.htm|ULONG]]) Specifies the stream operation (record or playback). The device driver should verify with how it has been initialized through IOCtls. The following stream operations are defined ( VSDs should verify with [[00424.htm|VSD_SET]]or [[00290.htm|VSD_OPEN]]settings):

STREAM_OPERATION_CONSUME Playback. <br />STREAM_OPERATION_PRODUCE Record.





=== DDCMDREGISTER Field - spcbkey ===

'''spcbkey'''([[00991.htm|SPCBKEY]]) Specifies input to the VSD or PDD (optional) buffer size.





=== DDCMDREGISTER Field - ulBufSize ===

'''ulBufSize'''([[00998.htm|ULONG]]) Specifies VSD or PDD output buffer size in bytes that will be sent to the driver. The caller will fill in a default value. If the device driver does not override this value, it will be used to determine the buffer size.

'''Note:'''The device driver sets this field to indicate the buffer size that it would like to receive from the streaming subsystem. For MIDI, this field is usually set to 512. For DMA-based audio or other systems where the interrupt rate equals the buffer rate, this field should be set to about 1/ 30 the quantity of data consumed or produced per second. This field supplies the system with a minimal buffer size for wave audio. Because other system elements also negotiate to determine buffer size and for software motion video, the system might provide buffers smaller than the size requested.





=== DDCMDREGISTER Field - ulNumBufs ===

'''ulNumBufs'''([[00998.htm|ULONG]]) Specifies VSD or PDD output total number of buffers that will be allocated. The caller will fill in a default value. If the device driver does not override this value, it will be used to determine the total number of buffers.





=== DDCMDREGISTER Field - ulAddressType ===

'''ulAddressType'''([[00998.htm|ULONG]]) Specifies VSD or PDD output (required) address pointer type to data buffer. The VSD or PDD tells the stream handler what type of address pointer it expects the data buffer to be. The stream handler then requests this address type to the SSM, so that the Sync/Stream Manager will send the correct type for each buffer request.

ADDRESS_TYPE_VIRTUAL 0 <br />ADDRESS_TYPE_PHYSICAL 1 <br />ADDRESS_TYPE_LINEAR 2





=== DDCMDREGISTER Field - ulBytesPerUnit ===

'''ulBytesPerUnit'''([[00998.htm|ULONG]]) Specifies VSD or PDD output (unused, set to zero). Device driver timing.





=== DDCMDREGISTER Field - mmtimePerUnit ===

'''mmtimePerUnit'''([[00941.htm|MMTIME]]) Specifies VSD or PDD output. Device driver timing. (Unused, set to zero.)





=== DDCMDREGISTER Field - dcbAudio ===

'''dcbAudio'''([[00803.htm|E_DCB]]) Specifies the input stream handler device control block ( DCB).





=== DDCMDREGISTER Field - hid ===

'''hid'''([[00808.htm|HID]]) Specifies the input stream handler ID to be used for all communication with the stream handler.





=== DDCMDSETUP ===

This data structure contains fields for the [[00190.htm|DDCMD_SETUP]]message.

<pre class="western">typedef struct _ddcmd_setup_parm {
  ULONG           ulFunction;       /*  Function requested by stream handler. */
  HSTREAM         hStream;          /*  Stream handle. */
  PSETUP_PARM     pSetupParm;       /*  Pointer to SETUP_PARM. */
  ULONG           ulSetupParmSize;  /*  Size of SETUP_PARM. */
} DDCMDSETUP;
</pre>




=== DDCMDSETUP Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDSETUP Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle that identifies the stream instance for this event.





=== DDCMDSETUP Field - pSetupParm ===

'''pSetupParm'''([[00955.htm|PSETUP_PARM]]) Points to the [[00955.htm|SETUP_PARM]]data structure.





=== DDCMDSETUP Field - ulSetupParmSize ===

'''ulSetupParmSize'''([[00998.htm|ULONG]]) The size of the [[00955.htm|SETUP_PARM]]data structure.





=== DDCMDSTATUS ===

This data structure contains fields for the [[00197.htm|DDCMD_STATUS]]message.

<pre class="western">typedef struct _ddcmd_status_parm {
  ULONG            ulFunction;    /*  Function requested by stream handler. */
  HSTREAM          hStream;       /*  Stream handle. */
  PSTATUS_PARM     pStatus;       /*  Pointer to STATUS_PARM. */
  ULONG            ulStatusSize;  /*  Size or position time. */
} DDCMDSTATUS;
</pre>




=== DDCMDSTATUS Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the stream handler.





=== DDCMDSTATUS Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle that identifies the stream instance for this event.





=== DDCMDSTATUS Field - pStatus ===

'''pStatus'''([[00995.htm|PSTATUS_PARM]]) A pointer to the current position time as output. See [[00995.htm|STATUS_PARM]].





=== DDCMDSTATUS Field - ulStatusSize ===

'''ulStatusSize'''([[00998.htm|ULONG]]) Specifies the size or position time as output.





=== E_DCB ===

This structure contains device-specific information. It is used at stream creation by the application media control device to deliver device-specific information to the source or target stream handlers.

<pre class="western">typedef struct _E_DCB {
  ULONG     ulDCBLen;                 /*  Length of structure. */
  SZ        szDevName[MAX_SPI_NAME];  /*  Device driver name. */
  ULONG     ulSysFileNum;             /*  File handle number. */
} E_DCB;

typedef   E _ DCB   FAR   * PE _ DCB ; </pre>




=== E_DCB Field - ulDCBLen ===

'''ulDCBLen'''([[00998.htm|ULONG]]) Length of the device control block.





=== E_DCB Field - szDevName[MAX_SPI_NAME] ===

'''szDevName[MAX_SPI_NAME]'''([[00997.htm|SZ]]) Identifies the device driver that the stream handler connects to for a particular stream instance. For stream handler device drivers, inter-device communication (IDC) is used to call the physical device driver. The device driver name must not be more than eight characters (excluding the file extension).





=== E_DCB Field - ulSysFileNum ===

'''ulSysFileNum'''([[00998.htm|ULONG]]) File handle number.





=== HEVENT ===

Event handle.

<pre class="western">typedef ULONG HEVENT;</pre>




=== HID ===

Stream handler ID.

<pre class="western">typedef ULONG HID;</pre>




=== HSTREAM ===

Stream handle.

<pre class="western">typedef ULONG HSTREAM;</pre>




=== HVSD ===

VSD handle.

<pre class="western">typedef PVOID HVSD;</pre>




=== HWND ===

Window handle.

<pre class="western">typedef LHANDLE HWND;</pre>




=== LINECONNECTIONS ===

This structure contains data for the [[00338.htm|VSD_QUERYMIXCONNECTIONS]]and the [[00460.htm|VSD_ SETMIXCONNECTIONS]]messages, and the [[00568.htm|MIX_GETCONNECTIONS]]and [[00576.htm|MIX_ SETCONNECTIONS]]IOCtls.

<pre class="western">typedef struct _LINECONNECTIONS {
  ULONG     ulLength;       /*  Length of the structure. */
  ULONG     ulConnections;  /*  Connection information. */
  ULONG     ulLine;         /*  Line to get connections information for. */
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS ; </pre>




=== LINECONNECTIONS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== LINECONNECTIONS Field - ulConnections ===

'''ulConnections'''([[00998.htm|ULONG]]) Line(s) that ''ulLine''is connected to.

Valid flags are:

SINK_LINE_OUT Line out connection.

SINK_SPEAKER Speaker connection.

SINK_HEADPHONES Headphones connection.

SINK_NULL Sink to nothing (remove all connections from this line).

SINK_ALL Sink to everything.

SINK_WAVE Wave connection.

SINK_MIDI Midi connection.





=== LINECONNECTIONS Field - ulLine ===

'''ulLine'''([[00998.htm|ULONG]]) Line to get connections information for.

The line described in ulLine field can have the following values:

SOURCE_SYNTHESIZER Midi connection.

SOURCE_LINE Line connection.

SOURCE_INTERNAL_AUDIO Internal audio connection.

SOURCE_MICROPHONE Microphone connection.

SOURCE_WAVE Wave connection.

SOURCE_PC_SPEAKER PC speaker connection.

SOURCE_NULL Source is nothing (remove all connections to this line).

SOURCE-MIDI Midi connection.





=== LONG ===

Signed integer in the range -2 147 483 648 through 2 147 483 647.

<pre class="western">#define LONG long</pre>
'''Note:'''Where this data type represents a graphic coordinate in world or model space, its value is restricted to -134 217 728 through 134 217 727.

A graphic coordinate in device or screen coordinates is restricted to -32 768 through 32 767.

The value of a graphic coordinate may be further restricted by any transforms currently in force, including the positioning of the origin of the window on the screen. In particular, coordinates in world or model space must not generate coordinate values after transformation (that is, in device or screen space) outside the range -32 768 through 32 767.





=== MCI_AUDIO_BUFFER ===

This structure contains fields for the [[00521.htm|AUDIO_BUFFER]]function.

<pre class="western">typedef struct _buffer {
  ULONG     ulFlags;         /*  Indicates error condition. */
  ULONG     ulReadBufSize;   /*  Data in Read queue. */
  ULONG     ulWriteBufSize;  /*  Data in Write queue. */
  ULONG     ulReadBufTime;   /*  Data in Read queue (in ms). */
  ULONG     ulWriteBufTime;  /*  Data in Write queue (in ms). */
  ULONG     ulReadBufMax;    /*  Max. data in Read queue. */
  ULONG     ulWriteBufMax;   /*  Max. data in Write queue. */
  ULONG     ulPosition;      /*  Position. */
  ULONG     ulPositionType;  /*  Type of position units. */
  LONG      lReadBufCap;     /*  Capacity of Read queue. */
  LONG      lWriteBufCap;    /*  Capacity of Write queue. */
  LONG      lRequestBufCap;  /*  Max. # of requests. */
} MCI_AUDIO_BUFFER;

typedef   MCI _ AUDIO _ BUFFER   FAR   * LPMCI _ AUDIO _ BUFFER ; </pre>




=== MCI_AUDIO_BUFFER Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Indicates an error condition occurred. The possible error states that can be flagged are:

<pre class="western">AUDIO_UNDERRUN   1
AUDIO_OVERRUN    2</pre>






=== MCI_AUDIO_BUFFER Field - ulReadBufSize ===

'''ulReadBufSize'''([[00998.htm|ULONG]]) Amount of data in Read queue in bytes.





=== MCI_AUDIO_BUFFER Field - ulWriteBufSize ===

'''ulWriteBufSize'''([[00998.htm|ULONG]]) Amount of data in Write queue in bytes.





=== MCI_AUDIO_BUFFER Field - ulReadBufTime ===

'''ulReadBufTime'''([[00998.htm|ULONG]]) Amount of data in Read queue in milliseconds.





=== MCI_AUDIO_BUFFER Field - ulWriteBufTime ===

'''ulWriteBufTime'''([[00998.htm|ULONG]]) Amount of data in Write queue in milliseconds.





=== MCI_AUDIO_BUFFER Field - ulReadBufMax ===

'''ulReadBufMax'''([[00998.htm|ULONG]]) Maximum number of bytes ever in Read queue.





=== MCI_AUDIO_BUFFER Field - ulWriteBufMax ===

'''ulWriteBufMax'''([[00998.htm|ULONG]]) Maximum number of bytes ever in Write queue.





=== MCI_AUDIO_BUFFER Field - ulPosition ===

'''ulPosition'''([[00998.htm|ULONG]]) Time count since beginning of operation.





=== MCI_AUDIO_BUFFER Field - ulPositionType ===

'''ulPositionType'''([[00998.htm|ULONG]]) Specifies the type of position units. The defined values for this field are:

<pre class="western">POS_MSECS       0    /* Position units in milliseconds
                        since start                            */
MIDI_CLOCKS     1    /* Position units in # of MIDI clocks
                        since start                            */
POS_BYTES       2    /* Position data in bytes                 */
SMPTE_24       24    /* Position corresponds with SMPTE 24
                        frames/sec                             */
SMPTE_25       25    /* Position corresponds with SMPTE 25
                        frames/sec                             */
SMPTE_30DF     29    /* Position corresponds with SMPTE 30
                        drop frame                             */
SMPTE_30       30    /* Position corresponds with SMPTE 30
                        frames/sec                             */</pre>






=== MCI_AUDIO_BUFFER Field - lReadBufCap ===

'''lReadBufCap'''([[00816.htm|LONG]]) Capacity of Read queue; ''-1''if variable.





=== MCI_AUDIO_BUFFER Field - lWriteBufCap ===

'''lWriteBufCap'''([[00816.htm|LONG]]) Capacity of Write queue; ''-1''if variable.





=== MCI_AUDIO_BUFFER Field - lRequestBufCap ===

'''lRequestBufCap'''([[00816.htm|LONG]]) Maximum number of requests that can be queued.





=== MCI_AUDIO_CAPS ===

This structure contains fields for the [[00558.htm|AUDIO_CAPABILITY]]function.

<pre class="western">typedef struct _MCI_AUDIO_CAPS {
  ULONG     ulLength;         /*  Input.  Structure length. */
  ULONG     ulSamplingRate;   /*  Input/Output.  Sampling rate to query. */
  ULONG     ulChannels;       /*  Input/Output.  Channels to query. */
  ULONG     ulBitsPerSample;  /*  Input/Output.  Bits per sample to query. */
  ULONG     ulDataType;       /*  Input/Output.  RIFF data type to query. */
  ULONG     ulOperation;      /*  Input/Output.  OPERATION_PLAY or OPERATION_RECORD. */
  ULONG     ulSupport;        /*  Output.  Boolean. */
  ULONG     ulDataSubType;    /*  Output.  Data subtype to use. */
  ULONG     ulResourceUnits;  /*  Output.  Resource units in this mode. */
  ULONG     ulResourceClass;  /*  Output.  Resource class for this mode. */
  ULONG     ulBlockAlign;     /*  Output.  Block alignment for this mode. */
  BOOL      fCanRecord;       /*  Unused */
  ULONG     ulFlags;          /*  Output.  Flags. */
  ULONG     ulCapability;     /*  Output.  Capability of the device. */
} MCI_AUDIO_CAPS;

typedef   MCI _ AUDIO _ CAPS   FAR   * PAUDIO _ CAPS ; </pre>




=== MCI_AUDIO_CAPS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Input. Structure length.





=== MCI_AUDIO_CAPS Field - ulSamplingRate ===

'''ulSamplingRate'''([[00998.htm|ULONG]]) Input/Output. Sampling rate to query.





=== MCI_AUDIO_CAPS Field - ulChannels ===

'''ulChannels'''([[00998.htm|ULONG]]) Input/Output. Channels to query.





=== MCI_AUDIO_CAPS Field - ulBitsPerSample ===

'''ulBitsPerSample'''([[00998.htm|ULONG]]) Input/Output. Bits per sample to query.





=== MCI_AUDIO_CAPS Field - ulDataType ===

'''ulDataType'''([[00998.htm|ULONG]]) Input/Output. RIFF data type to query. The definitions are in OS2MEDEF.H. A sample data type would be DATATYPE_WAVEFORM.





=== MCI_AUDIO_CAPS Field - ulOperation ===

'''ulOperation'''([[00998.htm|ULONG]]) Input/Output. OPERATION_PLAY or OPERATION_RECORD.





=== MCI_AUDIO_CAPS Field - ulSupport ===

'''ulSupport'''([[00998.htm|ULONG]]) Output. Boolean. Indicates if the device driver supports this mode.

Following are the valid return codes for ''ulSupport'':

SUPPORT_SUCCESS Device supports this mode.

UNSUPPORTED_RATE Unsupported sampling rate.

UNSUPPORTED_CHANNELS Unsupported sampling rate.

UNSUPPORTED_BPS Unsupported bits per sample.

UNSUPPORTED_DATATYPE Unsupported data type.

UNSUPPORTED_OPERATION Unsupported operation.





=== MCI_AUDIO_CAPS Field - ulDataSubType ===

'''ulDataSubType'''([[00998.htm|ULONG]]) Output. Data subtype to use. Returned by device. The definitions are in OS2MEDEF.H.





=== MCI_AUDIO_CAPS Field - ulResourceUnits ===

'''ulResourceUnits'''([[00998.htm|ULONG]]) Output. Data subtype to use. Returned by device.





=== MCI_AUDIO_CAPS Field - ulResourceClass ===

'''ulResourceClass'''([[00998.htm|ULONG]]) Output. Resource class for this mode. Returned by device.





=== MCI_AUDIO_CAPS Field - ulBlockAlign ===

'''ulBlockAlign'''([[00998.htm|ULONG]]) Output. Block alignment for this mode. Returned by device.





=== MCI_AUDIO_CAPS Field - fCanRecord ===

'''fCanRecord'''([[00751.htm|BOOL]]) Unused





=== MCI_AUDIO_CAPS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Output. Flags. Returned by device.





=== MCI_AUDIO_CAPS Field - ulCapability ===

'''ulCapability'''([[00998.htm|ULONG]]) Output. Capability of the device. Returned by device.

ulCapability can contain the following driver capabilities:+

SUPPORTED_MIX Supports mixing capabilities.

SUPPORTED_RIFF_MODES Supports Riff data types on audio init.

SUPPORTED_CAP Supports capability IOCtls.





=== MCI_AUDIO_CHANGE ===

This structure contains fields for the [[00506.htm|AUDIO_STATUS]]function.

<pre class="western">typedef struct _MCI_AUDIO_CHANGE {
  VOID FAR             *pvDevInfo;       /*  Pointer to information. */
  LONG                  lInput;          /*  Reserved. */
  LONG                  lOutput;         /*  Reserved. */
  LONG                  lMonitor;        /*  Record monitor level. */
  LONG                  lVolume;         /*  Volume setting. */
  LONG                  lVolumeDelay;    /*  Volume delay. */
  LONG                  lBalance;        /*  Balance setting. */
  LONG                  lBalanceDelay;   /*  Balance delay. */
  LONG                  lTreble;         /*  Treble tone-control setting. */
  LONG                  lBass;           /*  Base tone-control setting. */
  LONG                  lPitch;          /*  Pitch control setting. */
  MCI_AUDIO_DEVID       rInputList[8];   /*  Input list. */
  MCI_AUDIO_DEVID       rOutputList[8];  /*  Output list. */
  LPMCI_AUDIO_DEVID     prMoreInputs;    /*  Pointer to additional input. */
  LPMCI_AUDIO_DEVID     prMoreOutputs;   /*  Pointer to additional output. */
  LONG                  lGain;           /*  Gain control setting. */
  VOID FAR             *pvModeInfo;      /*  Pointer to mode-specific info. */
} MCI_AUDIO_CHANGE;

typedef   MCI _ AUDIO _ CHANGE   FAR   * LPMCI _ AUDIO _ CHANGE ; </pre>




=== MCI_AUDIO_CHANGE Field - pvDevInfo ===

'''pvDevInfo'''([[01203.htm|VOID FAR *]]) Pointer to a data structure containing device- dependent information. For example, for the M-ACPA card, ''pvDevInfo''points to a [[00920.htm|MCI_TRACK_INFO]]structure. This field is ignored if its value is NULL.





=== MCI_AUDIO_CHANGE Field - lInput ===

'''lInput'''([[00816.htm|LONG]]) Reserved. Used in v0 for input select.





=== MCI_AUDIO_CHANGE Field - lOutput ===

'''lOutput'''([[00816.htm|LONG]]) Reserved. Used in v0 for output select.





=== MCI_AUDIO_CHANGE Field - lMonitor ===

'''lMonitor'''([[00816.htm|LONG]]) Record monitor level.





=== MCI_AUDIO_CHANGE Field - lVolume ===

'''lVolume'''([[00816.htm|LONG]]) Volume setting; linear 0 min to 0x7FFFFFFF.





=== MCI_AUDIO_CHANGE Field - lVolumeDelay ===

'''lVolumeDelay'''([[00816.htm|LONG]]) Number of milliseconds over which change occurs.





=== MCI_AUDIO_CHANGE Field - lBalance ===

'''lBalance'''([[00816.htm|LONG]]) Balance setting 0 = left, 0x7FFFFFFF = right.





=== MCI_AUDIO_CHANGE Field - lBalanceDelay ===

'''lBalanceDelay'''([[00816.htm|LONG]]) Number of milliseconds over which change occurs.





=== MCI_AUDIO_CHANGE Field - lTreble ===

'''lTreble'''([[00816.htm|LONG]]) Treble tone-control setting.





=== MCI_AUDIO_CHANGE Field - lBass ===

'''lBass'''([[00816.htm|LONG]]) Base tone-control setting.





=== MCI_AUDIO_CHANGE Field - lPitch ===

'''lPitch'''([[00816.htm|LONG]]) Pitch control setting.





=== MCI_AUDIO_CHANGE Field - rInputList[8] ===

'''rInputList[8]'''([[00868.htm|MCI_AUDIO_DEVID]]) Input devices are specified using an array of [[00868.htm|MCI_AUDIO_DEVID]]data structures in the ''rInputList''field. Unused entries are set to NULL_INPUT. The [[00868.htm|MCI_AUDIO_DEVID]]structure permits device specification by type and ordinal number (for those audio adapters that support more than one device of a specific type). For example, to specify stereo line input, set:

<pre class="western">rInputList[0].ulDevType = STEREO_LINE_INPUT
rInputList[0].ulDevNum  = 1</pre>






=== MCI_AUDIO_CHANGE Field - rOutputList[8] ===

'''rOutputList[8]'''([[00868.htm|MCI_AUDIO_DEVID]]) Output devices are specified using an array of [[00868.htm|MCI_AUDIO_DEVID]]data structures in the ''rOutputList''field. Unused entries are set to NULL_OUTPUT. The [[00868.htm|MCI_AUDIO_DEVID]]structure permits device specification by type and ordinal number (for those audio adapters that support more than one device of a specific type). For example, to specify stereo line output, set:

<pre class="western">rOutputList[0].ulDevType = STEREO_LINE_OUTPUT
rOutputList[0].ulDevNum  = DEVICE_1.</pre>






=== MCI_AUDIO_CHANGE Field - prMoreInputs ===

'''prMoreInputs'''([[00868.htm|LPMCI_AUDIO_DEVID]]) Pointer to additional input device IDs.





=== MCI_AUDIO_CHANGE Field - prMoreOutputs ===

'''prMoreOutputs'''([[00868.htm|LPMCI_AUDIO_DEVID]]) Pointer to additional output device IDs.





=== MCI_AUDIO_CHANGE Field - lGain ===

'''lGain'''([[00816.htm|LONG]]) Input (record) gain-control setting.





=== MCI_AUDIO_CHANGE Field - pvModeInfo ===

'''pvModeInfo'''([[01203.htm|VOID FAR *]]) Pointer to a mode-specific data structure. For MIDI, this points to a [[00925.htm|MIDI_INFO]]structure.





=== MCI_AUDIO_CONTROL ===

This structure contains fields for the [[00513.htm|AUDIO_CONTROL]]function.

<pre class="western">typedef struct _MCI_AUDIO_CONTROL {
  USHORT     usIOCtlRequest;
  VOID      *pbRequestInfo;
  ULONG      ulPosition;
  SHORT      sReturnCode;
} MCI_AUDIO_CONTROL;

typedef   MCI _ AUDIO _ CONTROL   FAR   * LPMCI _ AUDIO _ CONTROL </pre>




=== MCI_AUDIO_CONTROL Field - usIOCtlRequest ===

'''usIOCtlRequest'''([[00999.htm|USHORT]]) IOCtl request to be executed. The defined values for this field are:

AUDIO_CHANGE (0) Enables an application to change adapter characteristics. It is issued while the audio device is open. The characteristics contained in the [[00845.htm|MCI_AUDIO_CHANGE]]structure such as input source can be changed by this request.

'''Note:'''AUDIO_CHANGE requests have the potential to break the data flow. Some audio devices might require that input, output, and monitor selections be performed prior to starting a change operation.

To change an adapter's characteristics, the desired values should be placed in the respective fields and the request issued. Notice that all possible combinations of these fields are not necessarily supported by the device driver. Invalid combinations result in an error returned by AUDIO_CHANGE.

The effects of issuing this request can vary for each requested change. If a given field is to remain unchanged, set that field to AUDIO_IGNORE (-1).

AUDIO_START (1) Initiates the flow of audio data to or from the adapter. It also causes the internal position and timing values to be set to the value contained in ''ulPosition''. Therefore, an immediate call to AUDIO_BUFFER returns a position value equal to the ''ulPosition''value specified in AUDIO_ START. The audio device must be opened and initialized (through OPEN and [[00498.htm|AUDIO_INIT]]requests) before calling AUDIO_START. Otherwise, an error is returned.

There is no ''pbRequestInfo''field for AUDIO_START.

AUDIO_STOP (2) Stops the current activity in progress on the audio device. For example, if the device was recording, the recording activity would be stopped. This operation does not change the current configuration (such as sampling rate, input source, and so forth) of the device; it simply terminates the current operation. Consequently, it also stops data flow between the device driver and the application. Any data left in the buffers is discarded. Notice that the Write buffers can be drained using the AUDIO_WAIT request. Use the AUDIO_PAUSE operation instead of AUDIO_STOP if the operation must be resumed at the point it left off.

The ''ulPosition''value is used to specify when the stop is to occur. A value of less than the current position or ''0''results in an immediate execution of the stop.

There is no ''pbRequestInfo''field for AUDIO_STOP.

AUDIO_PAUSE (3) Used to suspend all data flow between the application and the adapter. This request does not flush the kernel buffers or the adapter buffers. Data flow can be resumed by using AUDIO_RESUME. If recording, data is lost during the time that the device driver is paused.

The ''pbRequestInfo''value is used to specify when the pause is to occur. A value of less than the current position results in an immediate pause.

There is no ''pbRequestInfo''field for AUDIO_PAUSE.

AUDIO_RESUME (4) Used to resume the flow of data that was suspended by AUDIO_PAUSE. Notice that an ''ulPosition''value of non-zero is not currently defined and should not be used.

There is no ''pbRequestInfo''field for AUDIO_RESUME.





=== MCI_AUDIO_CONTROL Field - pbRequestInfo ===

'''pbRequestInfo'''Pointer to a structure that contains information specific to each type of IOCtl request. See the IOCtl request descriptions above for specifics on what ''pbRequestInfo''points to for each request. Notice that these requests are executed at a point in time specified by the caller.





=== MCI_AUDIO_CONTROL Field - ulPosition ===

'''ulPosition'''([[00998.htm|ULONG]]) Number of units before the request should be executed. This value is used to specify cue points. Caller requests are executed ''ulPosition''number of units from the beginning of the first Write operation after opening a track. Depending on the DSP code loaded and the current mode of operation, units can be bytes, time, or some other unit of measure. For example, to increase the volume of a track after the first 1,000 milliseconds of data have been written to the adapter, issue an AUDIO_ CHANGE request with ''ulPosition''set to 1000. This example assumes that the track information pointed to by ''pbRequestInfo''has been initialized appropriately, and that ''MCI_AUDIO_BUFFER.ulPositionType''= POS_MSECS.

If a request is made for a position number that has already occurred, it is processed immediately. Requests with a position number of ''0''are also processed immediately.





=== MCI_AUDIO_CONTROL Field - sReturnCode ===

'''sReturnCode'''([[00973.htm|SHORT]]) Used to return any error code. The defined values for this field are:

<pre class="western">AC_UNINITED  1           /* Device must be initialized or loaded first */
FULL_QUEUE   2           /* Max. number of requests exceeded */
AC_UNPAUSED  3           /* Resume issued, but device not paused */
INVALID_REQUEST      4   /* Bad MCI_AUDIO_CONTROL.usIOCtlRequest */
AC_UNSTARTED         5   /* Device must be started first */
INVALID_INPUT_LIST   7   /* Device in MCI_AUDIO_CHANGE.input_list is not
                            supported */
INVALID_OUTPUT_LIST  8   /* Device in MCI_AUDIO_CHANGE.output_list is not
                            supported */</pre>






=== MCI_AUDIO_DEVID ===



<pre class="western">typedef struct _MCI_AUDIO_DEVID {
  ULONG     ulDevType;
  ULONG     ulDevNum;
} MCI_AUDIO_DEVID;

typedef   MCI _ AUDIO _ DEVID   FAR   * LPMCI _ AUDIO _ DEVID ; </pre>




=== MCI_AUDIO_DEVID Field - ulDevType ===

'''ulDevType'''([[00998.htm|ULONG]]) Defined values for ''ulDevType''are shown for input and output devices:

<pre class="western">/* Input Devices */
#define  NULL_INPUT                   0
#define  STEREO_LINE_INPUT            1
#define  LEFT_LINE_INPUT              2
#define  RIGHT_LINE_INPUT             3
#define  MIC_INPUT                    4
#define  BOOSTED_MIC_INPUT            5
#define  PHONE_LINE_INPUT             6
#define  HANDSET_INPUT                7
#define  SYNTH_INPUT                  8
#define  DIGITAL_PHONE_LINE_INPUT     9
#define  DIGITAL_HANDSET_INPUT       10
#define  MIDI_IN_PORT                11
#define  LOOPBACK                    12
#define  DEFAULT_INPUT               0xFFFFFFFF
/* Values between 0x20000000 and 0xFFFFFFFE are reserved */

/* Output Devices */
#define  NULL_OUTPUT                  0
#define  STEREO_LINE_OUTPUT           1
#define  LEFT_LINE_OUTPUT             2
#define  RIGHT_LINE_OUTPUT            3
#define  SPEAKER_OUTPUT               4
#define  HEADPHONES_OUTPUT            5
#define  PHONE_LINE_OUTPUT            6
#define  HANDSET_OUTPUT               7
#define  SYNTH_OUTPUT                 8
#define  DIGITAL_PHONE_LINE_OUTPUT    9
#define  DIGITAL_HANDSET_OUTPUT      10
#define  MIDI_OUT_PORT               11
#define  DEFAULT_OUTPUT              0xFFFFFFFF
/* Values between 0x20000000 and 0xFFFFFFFE are reserved */</pre>






=== MCI_AUDIO_DEVID Field - ulDevNum ===

'''ulDevNum'''([[00998.htm|ULONG]]) The defined values for ''ulDevNum''are:

<pre class="western">#define  DEFAULT_DEVICE               0
#define  DEVICE_1                     1
#define  DEVICE_2                     2</pre>






=== MCI_AUDIO_HPI ===

This structure contains fields for the [[00543.htm|AUDIO_HPI]]function.

<pre class="western">typedef struct _hpi {
  VOID FAR                *pvEntry ();     /*  Pointer to direct-call entry point. */
  VOID FAR                *pvCallBack ();  /*  Pointer to callback routine. */
  LPMCI_AUDIO_IOBUFFER     prXBuff;        /*  Pointer to new Transmit buffer. */
  LPMCI_AUDIO_IOBUFFER     prRBuff;        /*  Pointer to new Receive buffer. */
  USHORT                   usFlags;        /*  Reserved. */
} MCI_AUDIO_HPI;

typedef   MCI _ AUDIO _ HPI   FAR   * LPMCI _ AUDIO _ HPI ; </pre>




=== MCI_AUDIO_HPI Field - pvEntry () ===

'''pvEntry ()'''([[01203.htm|VOID FAR *]]) Pointer to the direct-call entry point. The direct call interface is defined below.

<pre class="western">void (far *iobuf.ep)(short funcid, void far *data, short len);

/* Definitions for funcid */

EP_OPEN       0
EP_CLOSE      1
EP_READ       2
EP_WRITE      3
EP_INIT       4
EP_STATUS     5
EP_CONTROL    6
EP_BUFFER     7
EP_LOAD       8
EP_WAIT       9
EP_HPI       10
EP_UPDATE    11
/* On return, AX contains an error code, or 0 if successful */</pre>






=== MCI_AUDIO_HPI Field - pvCallBack () ===

'''pvCallBack ()'''([[01203.htm|VOID FAR *]]) Pointer to the callback routine. The application passes the address of a callback routine (under DOS) or system semaphore handle (under OS/2) in ''pvCallBack ()''. Notice that the DOS callback routine must be an interrupt routine, that is, it must return with an IRET, not a RET instruction. Care must be taken not to re-enter DOS. For example, the interrupt can occur while executing a DOS call. Any call to DOS made in the callback routine will result in DOS being entered a second time and will ''probably cause a system halt''.

If not NULL, the address is called (under DOS) or the semaphore is cleared (under OS/2) based on the state of the CBDATA, CBBLOCK, CBIOBUF, and CBERROR flags in ''usRunFlags'':

CBDATA The address is called (under DOS) or the semaphore is cleared (under OS/2) for each data byte sent to, or received from, the device. Notice that some devices transfer data to and from the host only in blocks, in which case this bit has the same effect as CBBLOCK.

CBBLOCK The address is called or the semaphore is cleared for each complete block of data sent to, or received from, the device.

CBIOBUF The address is called or the semaphore is cleared each time the entire contents of IOBUF are sent to, or received from, the device.

CBERROR The address is called or the semaphore is cleared each time a device error is detected by the device.

CBUNDERRUN The address is called or the semaphore is cleared each time an underrun or overrun is detected by the device.

This process will continue until either the device is stopped (or closed) or the [[00543.htm|AUDIO_HPI]]function is called again with ''pvCallBack ()''set to NULL. The device interrupt rate generally corresponds with the position resolution returned in ''lResolution''of the [[00877.htm|MCI_AUDIO_INIT]]structure.





=== MCI_AUDIO_HPI Field - prXBuff ===

'''prXBuff'''([[00892.htm|LPMCI_AUDIO_IOBUFFER]]) Pointer to new Transmit buffer to use. Set ''prXBuff''to NULL to use the default internal buffers.





=== MCI_AUDIO_HPI Field - prRBuff ===

'''prRBuff'''([[00892.htm|LPMCI_AUDIO_IOBUFFER]]) Pointer to new Receive buffer to use. Set ''prRBuff''to NULL to use the default internal buffers.

By default, the internal buffer sizes are usually 512 bytes. Any buffers provided must be an even number of bytes in length.





=== MCI_AUDIO_HPI Field - usFlags ===

'''usFlags'''([[00999.htm|USHORT]]) Reserved.





=== MCI_AUDIO_INIT ===

This structure contains fields for the [[00498.htm|AUDIO_INIT]]function.

<pre class="western">typedef struct _init {
  LONG           lSRate;                 /*  Sampling rate. */
  LONG           lBitsPerSRate;          /*  # of bits per sample. */
  LONG           lBsize;                 /*  Block size. */
  SHORT          sMode;                  /*  Audio mode. */
  SHORT          sChannels;              /*  Number of audio channels. */
  LONG           lResolution;            /*  Resolution of position data. */
  CHAR           abLoadPath[LOAD_PATH];  /*  Path of DSP code to load. */
  ULONG          ulFlags;                /*  Fixed, signed, and so on. */
  ULONG          ulOperation;            /*  Desired operation. */
  SHORT          sReturnCode;            /*  Return code for operation. */
  SHORT          sSlotNumber;            /*  Slot number of adapter. */
  SHORT          sDeviceID;              /*  Adapter type ID. */
  VOID FAR      *pvReserved;             /*  Reserved field. */
  ULONG          ulVersionLevel;         /*  Version level of device driver. */
} MCI_AUDIO_INIT;

typedef   MCI _ AUDIO _ INIT   FAR   * LPMCI _ AUDIO _ INIT ; </pre>




=== MCI_AUDIO_INIT Field - lSRate ===

'''lSRate'''([[00816.htm|LONG]]) Indicates the sampling rate in Hz, if applicable.





=== MCI_AUDIO_INIT Field - lBitsPerSRate ===

'''lBitsPerSRate'''([[00816.htm|LONG]]) Indicates the number of bits per sample, if applicable .





=== MCI_AUDIO_INIT Field - lBsize ===

'''lBsize'''([[00816.htm|LONG]]) Indicates the data block size for blocked data. Some devices perform I/O in fixed block amounts. For these devices, a full block of data must be written to the device driver before it is written to the device (during playback). During Record operations, a full block of data must be received before it becomes available to the application. The ''lBsize''field should be less than or equal to 1024 bytes, however, it cannot be guaranteed not to exceed that size.





=== MCI_AUDIO_INIT Field - sMode ===

'''sMode'''([[00973.htm|SHORT]]) Indicates the general audio mode, for example, PCM, ADPCM, or MIDI. The defined values for ''sMode''are:

<pre class="western">ADPCM              1         /* AVC type ADPCM                */
PCM                2         /* PCM                           */
MU_LAW             3         /* Mu-law                        */
MIDI               4         /* MIDI                          */
A_LAW              5         /* A-law                         */
SOURCE_MIX         6         /* External analog audio source  */
SPV2               7         /* Reserved (Speech Viewer/2)    */
ADPCMXA            8         /* XA CD ROM                     */
DSSM               9         /* DS201 Standard mode           */
DSMM              10         /* DS201 Movie mode              */
CVSD              11         /* CVSD                          */
SPV2BCPCM         25         /* Reserved (Speech Viewer/2)    */
SPV2PCM           26         /* Reserved (Speech Viewer/2)    */
SPV2NONE          27         /* Reserved (Speech Viewer/2)    */
IDLE             999         /* Deinitialize the track        */
CLAIM_HDWR     32000         /* Claim hardware for other use  */</pre>






=== MCI_AUDIO_INIT Field - sChannels ===

'''sChannels'''([[00973.htm|SHORT]]) Indicates the number of audio channels, for example, mono is 1, stereo is 2.





=== MCI_AUDIO_INIT Field - lResolution ===

'''lResolution'''([[00816.htm|LONG]]) Set to indicate the resolution of position data returned by the device driver. For example, the M-ACPA device driver can return position data rounded to the nearest 100 milliseconds when playing AVC ADPCM (.1-second blocked) data.





=== MCI_AUDIO_INIT Field - abLoadPath[LOAD_PATH] ===

'''abLoadPath[LOAD_PATH]'''([[00753.htm|CHAR]]) If the digital signal processor (DSP) code must be loaded before the operation can be performed, the device driver sets the LOAD_CODE bit in ''ulFlags''. In this case, the name of the DSP file to be loaded is specified in the ''abLoadPath''field. Notice that the application must call AUDIO_LOAD before trying to perform Read or Write operations.

Keep a single copy of each DSP load module maintained and grouped together in a single subdirectory. This subdirectory can be referenced in the DOS APPEND command or the OS/2 DPATH CONFIG.SYS statement.

The maximum path length available for DSP code modules in ''abLoadPath''is:

<pre class="western">LOAD_PATH    260    /* DOS and OS/2 length is 260 */</pre>






=== MCI_AUDIO_INIT Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) A bit flag indicating several pieces of information. The defined values for ''ulFlags''are:

FIXED (0x00000001l) Specify that the data is fixed, as opposed to variable rate or size.

LEFT_ALIGNED (0x00000002l) Specify that the data is left aligned on a byte boundary. This field is applicable only if ''lBitsPerSRate''is not a multiple of ''8''.

RIGHT_ALIGNED (0x00000004l) Specify that the data is right aligned on a byte boundary. This bit is applicable only if ''lBitsPerSRate''is not a multiple of ''8''.

TWOS_COMPLEMENT (0x00000008l) Specify that the data is represented by using TWOS_COMPLEMENT signed format. If this bit and the SIGNED bit are both ''0'', the data is in unsigned format.

SIGNED (0x00000010l) Specify that the data is represented using signed magnitude format, whereby the highest bit is set to ''1''to indicate a negative value, and the lower bits specify the absolute value. If this bit and the TWOS_COMPLEMENT bit are both ''0'', the data is in unsigned format.

BIG_ENDIAN (0x00000020l) Specifies that the most significant bytes precede the least significant bytes. This bit is applicable only if ''lBitsPerSRate''is greater than ''8''(multibyte values).

RIFF_DATATYPE (0x00000040l) sMode contains a RIFF datatype.

PITCH (0x00100000l) Specifies that pitch control is supported.

INPUT (0x00200000l) Specifies that input select is supported.

OUTPUT (0x00400000l) Specifies that output select is supported.

MONITOR (0x00800000l) Specifies that monitor select is supported.

VOLUME (0x01000000l) Specifies that volume select is supported.

VOLUME_DELAY (0x02000000l) Specifies that volume delay is supported.

BALANCE (0x04000000l) Specifies that balance control is supported.

BALANCE_DELAY (0x08000000l) Specifies that balance delay is supported.

TREBLE (0x10000000l) Specifies that treble control is supported

BASS (0x20000000l) Specifies that bass control is supported.

BESTFIT_PROVIDED (0x40000000l) Indicates that the best fit is returned.

LOAD_CODE (0x80000000l) Indicates that a DSP load is needed.





=== MCI_AUDIO_INIT Field - ulOperation ===

'''ulOperation'''([[00998.htm|ULONG]]) Specifies the desired operation. The defined values for this field are:

<pre class="western">OPERATION_PLAY     0x80000001
OPERATION_RECORD   0x80000002
PLAY_AND_RECORD    0x80000003
ANALYSIS           0x80000006      /* Speech Viewer/2 */
DISTANCE           0x80000007      /* Speech Viewer/2 */
MIGRATION          0x80000008      /* Speech Viewer/2 */</pre>
Notice that the high-order bit is set in all cases.





=== MCI_AUDIO_INIT Field - sReturnCode ===

'''sReturnCode'''([[00973.htm|SHORT]]) Return code for the operation. The defined values for ''sReturnCode''are:

<pre class="western">NO_PLAY              1    /* Cannot play                       */
NO_RECORD            2    /* Cannot record                     */
NO_RECORD_AND_PLAY   3    /* Cannot both play and record       */
INVALID_REQUEST      4    /* Request was not valid             */
CONFLICT             5    /* Conflicting information was found */
OVERLOADED           6    /* Out of DSP MIPS or Memory         */
DOWNLEVEL_DD         7    /* DD is an earlier version than
                             the version requested by the
                             application                       */
DSP_LOAD_PENDING_ON_OTHER_TRK  8  /* Other track hasn't loaded DSP  */</pre>






=== MCI_AUDIO_INIT Field - sSlotNumber ===

'''sSlotNumber'''([[00973.htm|SHORT]]) If the call is successful, the slot number of the device is returned in the ''sSlotNumber''field.





=== MCI_AUDIO_INIT Field - sDeviceID ===

'''sDeviceID'''([[00973.htm|SHORT]]) If the call is successful, the type of device is returned in the ''sDeviceID''field. The defined values used by ''sDeviceID''are:

<pre class="western">MINIDD               0    /* Minimal device driver             */
ACPA                 1    /* IBM ACPA                          */
MACPA                2    /* IBM M-ACPA                        */
MPU401               3    /* Roland MPU-401 or compatible      */
SOUND_BLASTER        4    /* Creative Labs Sound Blaster       */
IMF                  5    /* IBM Music Feature                 */
PS1                  6    /* IBM Personal System/1 audio
                             feature                           */
PAS16                7    /* Media Vision ProAudio Spectrum 16 */
DS201                9    /* DS201 audio adapter               */</pre>






=== MCI_AUDIO_INIT Field - pvReserved ===

'''pvReserved'''([[01203.htm|VOID FAR *]]) The caller must fill this field in with a ulSysFileNumber.





=== MCI_AUDIO_INIT Field - ulVersionLevel ===

'''ulVersionLevel'''([[00998.htm|ULONG]]) Specifies the audio device driver version. As audio device drivers evolve, some changes are sure to occur. The ''ulVersionLevel''field is used to allow new functions to be added to audio device drivers without losing compatibility with existing applications.

When an application calls AUDIO_INIT, it specifies the version level of the requested device driver. The audio device driver compares its version level with that passed by the application and ensures that they are compatible. If the device driver is an earlier version than that required by the application, it returns an error. If the version level of the device driver is newer than the application, the driver ensures that calls from the application are handled in a manner consistent with the version level of the application.

The value specified in ''ulVersionLevel''is the binary-coded decimal representation of the version and build level. For example, Version 1.0 Build 15 is coded 0x01000015. The high-order byte is the version, the next byte is the revision number, and the least significant two bytes are the build number.





=== MCI_AUDIO_IOBUFFER ===

This structure contains fields for the [[00543.htm|AUDIO_HPI]]function.

<pre class="western">typedef struct _MCI_AUDIO_IOBUFFER {
  LONG           lSize;       /*  Size of data buffers. */
  CHAR FAR      *pHead;       /*  Queue head pointer. */
  CHAR FAR      *pTail;       /*  Queue tail pointer. */
  LONG           lCount;      /*  # of bytes queued. */
  ULONG          ulPosition;  /*  Position counter. */
  LONG           lDelay;      /*  # of units before next I/O. */
  USHORT         usRunFlags;  /*  Start/stop/pause bits. */
  USHORT         usSelInc;
  CHAR FAR      *pBuffer;     /*  Array of pointers. */
} MCI_AUDIO_IOBUFFER;

typedef   MCI _ AUDIO _ IOBUFFER   FAR   * LPMCI _ AUDIO _ IOBUFFER ; </pre>




=== MCI_AUDIO_IOBUFFER Field - lSize ===

'''lSize'''([[00816.htm|LONG]]) Total size in bytes of the data buffers.





=== MCI_AUDIO_IOBUFFER Field - pHead ===

'''pHead'''([[00753.htm|CHAR FAR *]]) Queue head pointer (data added here).





=== MCI_AUDIO_IOBUFFER Field - pTail ===

'''pTail'''([[00753.htm|CHAR FAR *]]) Queue tail pointer (data removed here)





=== MCI_AUDIO_IOBUFFER Field - lCount ===

'''lCount'''([[00816.htm|LONG]]) Total number of data bytes currently queued.





=== MCI_AUDIO_IOBUFFER Field - ulPosition ===

'''ulPosition'''([[00998.htm|ULONG]]) Position counter.





=== MCI_AUDIO_IOBUFFER Field - lDelay ===

'''lDelay'''([[00816.htm|LONG]]) Number of pos units before the next I/O.





=== MCI_AUDIO_IOBUFFER Field - usRunFlags ===

'''usRunFlags'''([[00999.htm|USHORT]]) Start/stop/pause bits.





=== MCI_AUDIO_IOBUFFER Field - usSelInc ===

'''usSelInc'''([[00999.htm|USHORT]])





=== MCI_AUDIO_IOBUFFER Field - pBuffer ===

'''pBuffer'''([[00753.htm|CHAR FAR *]]) Array of pointers describing buffers.





=== MCI_AUDIO_LOAD ===

This structure contains fields for the [[00529.htm|AUDIO_LOAD]]function.

<pre class="western">typedef struct _load {
  CHAR FAR      *pbBuffer;  /*  Pointer to buffer. */
  ULONG          ulSize;    /*  Size of DSP code (in bytes). */
  ULONG          ulFlags;   /*  Indicates start or end of operation. */
} MCI_AUDIO_LOAD;

typedef   MCI _ AUDIO _ LOAD   FAR   * LPMCI _ AUDIO _ LOAD ; </pre>




=== MCI_AUDIO_LOAD Field - pbBuffer ===

'''pbBuffer'''([[00753.htm|CHAR FAR *]]) Pointer to buffer containing DSP code.





=== MCI_AUDIO_LOAD Field - ulSize ===

'''ulSize'''([[00998.htm|ULONG]]) Size of DSP code (in bytes).





=== MCI_AUDIO_LOAD Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Indicates start or end of operation. The defined values for this field are:

<pre class="western">LOAD_START    1    /* Indicates that this is the first block  */
LOAD_END      2    /* Indicates that this is the last block   */
LOAD_32BIT   10</pre>






=== MCI_AUDIO_STATUS ===

This structure contains fields for the [[00506.htm|AUDIO_STATUS]]function.

<pre class="western">typedef struct _stat {
  LONG                 lSRate;         /*  Sampling rate. */
  LONG                 lBitsPerSRate;  /*  # of bits per sample. */
  LONG                 lBsize;         /*  Block size. */
  SHORT                sMode;          /*  Mode. */
  SHORT                sChannels;      /*  # of channels. */
  ULONG                ulFlags;        /*  Flags. */
  ULONG                ulOperation;    /*  Operation. */
  MCI_AUDIO_CHANGE     rAudioChange;   /*  MCI_AUDIO_CHANGE structure. */
} MCI_AUDIO_STATUS;

typedef   MCI _ AUDIO _ STATUS   FAR   * LPMCI _ AUDIO _ STATUS ; </pre>




=== MCI_AUDIO_STATUS Field - lSRate ===

'''lSRate'''([[00816.htm|LONG]]) Indicates the sampling rate in Hz (if applicable).





=== MCI_AUDIO_STATUS Field - lBitsPerSRate ===

'''lBitsPerSRate'''([[00816.htm|LONG]]) Indicates the number of bits per sample (if applicable ).





=== MCI_AUDIO_STATUS Field - lBsize ===

'''lBsize'''([[00816.htm|LONG]]) Indicates the data block size for blocked data.





=== MCI_AUDIO_STATUS Field - sMode ===

'''sMode'''([[00973.htm|SHORT]]) Indicates the general audio mode, for example, PCM, ADPCM, or MIDI. The possible values are listed under the ''sMode''field of [[00877.htm|MCI_AUDIO_ INIT]].





=== MCI_AUDIO_STATUS Field - sChannels ===

'''sChannels'''([[00973.htm|SHORT]]) Indicates the number of audio channels, for example, mono is 1, stereo is 2.





=== MCI_AUDIO_STATUS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) A bit flag. The possible values are listed under the ''ulFlags''field of [[00877.htm|MCI_AUDIO_INIT]].





=== MCI_AUDIO_STATUS Field - ulOperation ===

'''ulOperation'''([[00998.htm|ULONG]]) Specifies the desired operation. The defined values for this field are:

<pre class="western">STOPPED               0x80000000
PLAYING               0x80000001
RECORDING             0x80000002
PLAYING_AND_RECORDING 0x80000003
UNINITIALIZED         0xFFFFFFFF</pre>
Notice that the value associated with the current operation is returned in the ''ulOperation''field.





=== MCI_AUDIO_STATUS Field - rAudioChange ===

'''rAudioChange'''([[00845.htm|MCI_AUDIO_CHANGE]]) An [[00845.htm|MCI_AUDIO_CHANGE]]data structure.





=== MCI_DEVICESETTINGS_PARMS ===

This structure contains fields for the MCI_DEVICESETTINGS message.

<pre class="western">typedef struct _MCI_DEVICESETTINGS_PARMS {
  HWND       hwndCallback;   /*  Window handle. */
  HWND       hwndNotebook;   /*  Handle to notebook window. */
  USHORT     usDeviceType;   /*  Device type. */
  PSZ        pszDeviceName;  /*  Logical device name. */
} MCI_DEVICESETTINGS_PARMS;

typedef   MCI _ DEVICESETTINGS _ PARMS   * PMCI _ DEVICESETTINGS _ PARMS ; </pre>




=== MCI_DEVICESETTINGS_PARMS Field - hwndCallback ===

'''hwndCallback'''([[00811.htm|HWND]]) A window handle to be used in returning asynchronous notification messages. This parameter must be specified if the MCI_NOTIFY flag is specified.





=== MCI_DEVICESETTINGS_PARMS Field - hwndNotebook ===

'''hwndNotebook'''([[00811.htm|HWND]]) Handle to notebook window.





=== MCI_DEVICESETTINGS_PARMS Field - usDeviceType ===

'''usDeviceType'''([[00999.htm|USHORT]]) Device type.





=== MCI_DEVICESETTINGS_PARMS Field - pszDeviceName ===

'''pszDeviceName'''([[00954.htm|PSZ]]) Logical device name.





=== MCI_TRACK_INFO ===



<pre class="western">typedef struct _info {
  USHORT     usMasterVolume;       /*  Master volume control. */
  USHORT     usDitherPct;          /*  Dither percent control. */
  USHORT     usMasterVolumeDelay;  /*  Master volume delay. */
  USHORT     usMasterBalance;      /*  Master balance control. */
} MCI_TRACK_INFO;

typedef   MCI _ TRACK _ INFO   FAR   * LPMCI _ TRACK _ INFO ; </pre>




=== MCI_TRACK_INFO Field - usMasterVolume ===

'''usMasterVolume'''([[00999.htm|USHORT]]) Master volume control.





=== MCI_TRACK_INFO Field - usDitherPct ===

'''usDitherPct'''([[00999.htm|USHORT]]) Dither percent control.





=== MCI_TRACK_INFO Field - usMasterVolumeDelay ===

'''usMasterVolumeDelay'''([[00999.htm|USHORT]]) Master volume delay.





=== MCI_TRACK_INFO Field - usMasterBalance ===

'''usMasterBalance'''([[00999.htm|USHORT]]) Master balance control.





=== MIDI_INFO ===

This structure contains MIDI-mode information.

<pre class="western">typedef struct _mode_info {
  SHORT     sTempo;         /*  Tempo. */
  SHORT     sCPQN;          /*  Timing. */
  SHORT     sMidiSwitches;  /*  Common MIDI switches. */
  SHORT     sReserved[5];   /*  Reserved field. */
} MIDI_INFO;
</pre>




=== MIDI_INFO Field - sTempo ===

'''sTempo'''([[00973.htm|SHORT]]) Tempo in 1/10 beats per minute (nominally 120).





=== MIDI_INFO Field - sCPQN ===

'''sCPQN'''([[00973.htm|SHORT]]) Timing clocks per quarter note (nominally 96).





=== MIDI_INFO Field - sMidiSwitches ===

'''sMidiSwitches'''([[00973.htm|SHORT]]) The following MIDI switches are defined:

<pre class="western">MIDI_THRU_OUT  1         /* Configure MIDI-Thru connector
                            as MIDI-Out                    */
MIDI_THRU_THRU 0         /* Configure MIDI-Thru connector
                            as MIDI-Thru                   */</pre>






=== MIDI_INFO Field - sReserved[5] ===

'''sReserved[5]'''([[00973.htm|SHORT]]) Reserved field.





=== MIXERCONTROL ===

This structure contains fields for the [[00348.htm|VSD_QUERYMIXCONTROL]]and the [[00469.htm|VSD_ SETMIXCONTROL]]messages and the [[00592.htm|MIX_GETCONTROL]]and [[00600.htm|MIX_SETCONTROL]]IOCtls.

<pre class="western">typedef struct _MIXERCONTROL {
  ULONG     ulLength;   /*  Length of the structure. */
  ULONG     ulLine;     /*  Line to control. */
  ULONG     ulControl;  /*  Input. Mixer attribute to control. */
  ULONG     ulSetting;  /*  Setting for mixer attribute. */
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR   * PMIXERCONTROL ; </pre>




=== MIXERCONTROL Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== MIXERCONTROL Field - ulLine ===

'''ulLine'''([[00998.htm|ULONG]]) Line to control.

This field can contain the following sources or sinks:

SOURCE_SYNTHESIZER Midi connection.

SOURCE_MIXER Source mixer connection.

SOURCE_LINE Line connection.

SOURCE_INTERNAL_AUDIO Internal audio connection.

SOURCE_MICROPHONE Microphone connection.

SOURCE_WAVE Wave connection.

SOURCE_PC_SPEAKER PC speaker connection.

SINK_LINE_OUT Line out connection.

SINK_SPEAKER Speaker connection.

SINK_HEADPHONES Headphones connection.

SINK_GENERIC Generic connection.

SINK_NULL Null connection.





=== MIXERCONTROL Field - ulControl ===

'''ulControl'''([[00998.htm|ULONG]]) Attribute to modify line.

This field can contain:

MIX_BALANCE Separate balance control.

MIX_ALC Auto level control.

MIX_MONITOR Monitor control.

MIX_CROSSOVER Crossover change.

MIX_LOUDNESS Loudness equalization.

MIX_MUTE Channel mute.

MIX_REVERB Reverb.

MIX_STEREOENHANCE Stereo enhance.

MIX_CUSTOM1 Custom effect #1.

MIX_CUSTOM2 Custom effect #2.

MIX_CUSTOM3 Custom effect #3.

MIX_BASS Bass.

MIX_TREBLE Treble.

MIX_PITCH Pitch modifications.

MIX_CHORUS Chorus.

MIX_VOLUME Volume controls.





=== MIXERCONTROL Field - ulSetting ===

'''ulSetting'''([[00998.htm|ULONG]]) Setting for mixer attribute.

For VSD_QUERYMIXCONTROL and VSD_SETMIXCONTROL messages, the ulSetting field can range from 0 to 100.

For MIX_GETCONTROL and MIX_SETCONTROL IOCtls, the ulSetting field can range from 0 to 0x7FFFFFFF. A value of 0xFFFFFFFF is invalid and should be ignored.





=== MIXERLINEINFO ===

This structure contains fields for the [[00358.htm|VSD_QUERYMIXLINE]]message and the [[00584.htm|MIX _GETLINEINFO]]IOCtl.

<pre class="western">typedef struct _MIXERLINEINFO {
  ULONG     ulLength;               /*  Input. Length of the structure. */
  ULONG     ulNumChannels;          /*  Output. Number of channels. */
  ULONG     ulSupport;              /*  Output. Supported mixer attributes. */
  ULONG     ulConnectionsPossible;  /*  Output. Possible connections. */
  ULONG     ulLine;                 /*  Input. The line to query. */
} MIXERLINEINFO;

typedef   MIXERLINEINFO   FAR   * PMIXERLINEINFO ; </pre>




=== MIXERLINEINFO Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== MIXERLINEINFO Field - ulNumChannels ===

'''ulNumChannels'''([[00998.htm|ULONG]]) Number of channels.





=== MIXERLINEINFO Field - ulSupport ===

'''ulSupport'''([[00998.htm|ULONG]]) Supported mixer attributes. The following values are defined for ''ulSupport'':

MIX_BALANCE Separate balance control.

MIX_ALC Auto level control.

MIX_MONITOR Monitor control.

MIX_CROSSOVER Crossover change.

MIX_LOUDNESS Loudness equalization.

MIX_MUTE Channel mute.

MIX_REVERB Reverb.

MIX_STEREOENHANCE Stereo enhance.

MIX_CUSTOM1 Custom effect #1.

MIX_CUSTOM2 Custom effect #2.

MIX_CUSTOM3 Custom effect #3.

MIX_BASS Bass.

MIX_TREBLE Treble.

MIX_PITCH Pitch modifications.

MIX_CHORUS Chorus.

MIX_VOLUME Volume controls.





=== MIXERLINEINFO Field - ulConnectionsPossible ===

'''ulConnectionsPossible'''([[00998.htm|ULONG]]) Lines ''ulLine''can connect to.





=== MIXERLINEINFO Field - ulLine ===

'''ulLine'''([[00998.htm|ULONG]]) Line to set or query information.

The ''ulLine''field must be filled in by the caller with one of the following VSD lines:

SOURCE_SYNTHESIZER Midi connection.

SOURCE_MIXER Mixer connection.

SOURCE_LINE Line connection.

SOURCE_INTERNAL_AUDIO Internal audio connection.

SOURCE_MICROPHONE Microphone connection.

SOURCE_WAVE Wave connection.

SOURCE_PC_SPEAKER PC speaker connection.





=== MMTIME ===

Universal Chinatown time (1/3000 second).

<pre class="western">typedef ULONG MMTIME;</pre>




=== MSG_REPORTEVENT ===

This structure contains fields for the SHC_REPORT_EVENT message (passed with SpiSendMsg).

<pre class="western">typedef struct _MSG_REPORTEVENT {
  ULONG      ulMsgLen;      /*  Length of structure. */
  HEVENT     hevent;        /*  Event handle. */
  ULONG      ulStreamTime;  /*  Time in milliseconds of stream position. */
} MSG_REPORTEVENT;

typedef   MSG _ REPORTEVENT   FAR   * PMSG _ REPORTEVENT ; </pre>




=== MSG_REPORTEVENT Field - ulMsgLen ===

'''ulMsgLen'''([[00998.htm|ULONG]]) Length of structure.





=== MSG_REPORTEVENT Field - hevent ===

'''hevent'''([[00807.htm|HEVENT]]) Event handle passed back to stream handler.





=== MSG_REPORTEVENT Field - ulStreamTime ===

'''ulStreamTime'''([[00998.htm|ULONG]]) Time in milliseconds of stream position.





=== MSG_REPORTINT ===

This structure contains fields for the SHC_REPORT_INT message (passed with SpiSendMsg).

<pre class="western">typedef struct _MSG_REPORTINT {
  ULONG     ulMsgLen;      /*  Length of structure. */
  PVOID     pBuffer;       /*  Return pointer. */
  ULONG     ulFlag;        /*  Reason for interrupt. */
  ULONG     ulStatus;      /*  Bytes read or written. */
  ULONG     ulStreamTime;  /*  Stream time in milliseconds. */
} MSG_REPORTINT;

typedef   MSG _ REPORTINT   FAR   * PMSG _ REPORTINT ; </pre>




=== MSG_REPORTINT Field - ulMsgLen ===

'''ulMsgLen'''([[00998.htm|ULONG]]) Length of structure.





=== MSG_REPORTINT Field - pBuffer ===

'''pBuffer'''([[01203.htm|PVOID]]) Pointer to buffer being returned (or null for no buffer to return).





=== MSG_REPORTINT Field - ulFlag ===

'''ulFlag'''([[00998.htm|ULONG]]) Specifies the reason for the interrupt. This field defines the following flags:

ERROR <br />STREAM_STOP_NOW <br />SHD_READ_COMPLETE <br />SHD_WRITE_COMPLETE

'''Note:'''

1.ERROR must be ORed with SHD_READ_COMPLETE or SHD_WRITE_COMPLETE.

2.Do not set SHD_READ_COMPLETE or SHD_WRITE_COMPLETE if not returning a buffer.





=== MSG_REPORTINT Field - ulStatus ===

'''ulStatus'''([[00998.htm|ULONG]]) Return code or bytes read or written.





=== MSG_REPORTINT Field - ulStreamTime ===

'''ulStreamTime'''([[00998.htm|ULONG]]) Stream time in milliseconds.





=== PFN ===

Pointer to a procedure.

<pre class="western">typedef _PFN *PFN;</pre>
In the header file, this is a two-part definition as shown below:

<pre class="western">typedef  int   (APIENTRY _PFN) ();
typedef  _PFN  *PFN;</pre>




=== PSHDFN ===

Pointer to a function prototype for a stream handler device entry routine.

<pre class="western">typedef ULONG (FAR *PSHDFN) (PVOID pParmIn);</pre>
In the header file, this is a two-part defintion as shown below:

<pre class="western">typedef ULONG (FAR *PSHDFN) (PVOID pParmIn);
typedef PVOID PSHDFN;</pre>




=== PSZ ===

Pointer to a null-terminated string.

If you are using C++ **, you may need to use PCSZ.

<pre class="western">typedef unsigned char *PSZ;</pre>




=== SETUP_PARM ===

This data structure contains fields for the ''pSetupParm''and ''ulSetupParmSize''fields of the [[00793.htm|DDCMDSETUP]]data structure.

<pre class="western">typedef struct _SETUP_PARM {
  ULONG     ulStreamTime;  /*  Stream time in milliseconds. */
  ULONG     ulFlags;       /*  Flags (input/output). */
} SETUP_PARM;
</pre>




=== SETUP_PARM Field - ulStreamTime ===

'''ulStreamTime'''([[00998.htm|ULONG]]) Specifies the stream time in milliseconds.





=== SETUP_PARM Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Device drivers should ignore this field.





=== SHD_COMMON ===

This data structure contains common fields between all SHD data structures.

<pre class="western">typedef struct _shd_common_parm {
  ULONG       ulFunction;  /*  Function requested by PDD. */
  HSTREAM     hStream;     /*  Stream handle. */
} SHD_COMMON;

typedef   SHD _ COMMON   * PSHD _ COMMON ; </pre>




=== SHD_COMMON Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the PDD.





=== SHD_COMMON Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle needed at interrupt time.





=== SHD_REPORTEVENT ===

This data structure contains fields for the [[00220.htm|SHD_REPORT_EVENT]]message.

<pre class="western">typedef struct _shd_reportevent_parm {
  ULONG       ulFunction;    /*  Function requested by PDD. */
  HSTREAM     hStream;       /*  Stream handle. */
  HEVENT      hEvent;        /*  Event handle. */
  ULONG       ulStreamTime;  /*  Time in milliseconds of stream position. */
} SHD_REPORTEVENT;

typedef   SHD _ REPORTEVENT   * PSHD _ REPORTEVENT ; </pre>




=== SHD_REPORTEVENT Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Function requested by PDD.





=== SHD_REPORTEVENT Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Stream handle.





=== SHD_REPORTEVENT Field - hEvent ===

'''hEvent'''([[00807.htm|HEVENT]]) Event handle passed back to stream handlers.





=== SHD_REPORTEVENT Field - ulStreamTime ===

'''ulStreamTime'''([[00998.htm|ULONG]]) Time in milliseconds of stream position.





=== SHD_REPORTINT ===

This data structure contains fields for the [[00227.htm|SHD_REPORT_INT]]message.

<pre class="western">typedef struct _shd_reportint_parm {
  ULONG       ulFunction;    /*  Function requested by PDD. */
  HSTREAM     hStream;       /*  Stream handle. */
  PVOID       pBuffer;       /*  Return pointer to last used buffer. */
  ULONG       ulFlag;        /*  Reason for interrupt. */
  ULONG       ulStatus;      /*  Return code or bytes read/written. */
  ULONG       ulStreamTime;  /*  Time in milliseconds of stream position. */
} SHD_REPORTINT;

typedef   SHD _ REPORTINT   * PSHD _ REPORTINT ; </pre>




=== SHD_REPORTINT Field - ulFunction ===

'''ulFunction'''([[00998.htm|ULONG]]) Specifies the function requested by the PDD.





=== SHD_REPORTINT Field - hStream ===

'''hStream'''([[00809.htm|HSTREAM]]) Specifies the stream handle so the stream handler knows which stream to process.





=== SHD_REPORTINT Field - pBuffer ===

'''pBuffer'''([[01203.htm|PVOID]]) Returns the pointer to the last used buffer.





=== SHD_REPORTINT Field - ulFlag ===

'''ulFlag'''([[00998.htm|ULONG]]) Specifies the reason for the interrupt. This field defines the following flags:

�ERROR <br />�STREAM_STOP_NOW <br />�SHD_READ_COMPLETE <br />�SHD_WRITE_COMPLETE

'''Note:'''Do not set SHD_READ_COMPLETE or SHD_WRITE_COMPLETE if not returning a buffer.

The STREAM_STOP_NOW flag is required. It forces the stream handler to release all buffers that have not been returned. Issue this flag if DDCMD_ STOP or if the VSD has remaining buffers.





=== SHD_REPORTINT Field - ulStatus ===

'''ulStatus'''([[00998.htm|ULONG]]) Specifies the status for the return code or the bytes read or written.





=== SHD_REPORTINT Field - ulStreamTime ===

'''ulStreamTime'''([[00998.htm|ULONG]]) Specifies the time in milliseconds of stream position.





=== SHORT ===

Signed integer in the range -32 768 through 32 767.

<pre class="western">#define SHORT short</pre>




=== SPCB ===

This structure describes a stream protocol of a specific data type.

<pre class="western">typedef struct _SPCB {
  ULONG       ulSPCBLen;        /*  SPCB length. */
  SPCBKEY     spcbkey;          /*  SPCB key. */
  ULONG       ulDataFlags;      /*  Data type flags. */
  ULONG       ulNumRec;         /*  Maximum number for records/buffers. */
  ULONG       ulBlockSize;      /*  Block size. */
  ULONG       ulBufSize;        /*  Buffer size. */
  ULONG       ulMinBuf;         /*  Minimum number of buffers. */
  ULONG       ulMaxBuf;         /*  Maximum number of buffers. */
  ULONG       ulSrcStart;       /*  Number of empty buffers. */
  ULONG       ulTgtStart;       /*  Number of full buffers. */
  ULONG       ulBufFlags;       /*  Buffer flags. */
  ULONG       ulHandFlags;      /*  Stream handler flags. */
  MMTIME      mmtimeTolerance;  /*  Resync tolerance value. */
  MMTIME      mmtimeSync;       /*  Sync pulse granularity. */
  ULONG       ulBytesPerUnit;   /*  Bytes per unit. */
  MMTIME      mmtimePerUnit;    /*  MMTIME per unit. */
} SPCB;

typedef   SPCB   FAR   * PSPCB ; </pre>




=== SPCB Field - ulSPCBLen ===

'''ulSPCBLen'''([[00998.htm|ULONG]]) Specifies the length of the stream protocol control block .





=== SPCB Field - spcbkey ===

'''spcbkey'''([[00991.htm|SPCBKEY]]) Data stream type and internal key. The internal key is used to differentiate between multiple SPCBs of the same data stream type. User defines should be addressed to 8,000,000(h) and higher.





=== SPCB Field - ulDataFlags ===

'''ulDataFlags'''([[00998.htm|ULONG]]) Attributes of the data type (that is, it specifies whether data or time cue points are supported by this data type).

SPCBDATA_CUEDATA This data type can support data cue-point events.

SPCBDATA_CUETIME This data type can support time cue-point events.

SPCBDATA_NOSEEK Seeking cannot be done on this data type.

SPCBDATA_YIELDTIME This flag indicates that the ''ulBytesPerUnit''field of the SPCB is interpreted as a millisecond yield time value. This yield takes place in between each I/O read operation. The yield time will also dynamically lower during data streaming depending on how many buffers in the stream are full. This flag is mutually exclusive with the SPCBHAND_ GENTIME flag and it can only be used with the SPCBBUF_INTERLEAVED flag. The maximum yield time is 1 second.





=== SPCB Field - ulNumRec ===

'''ulNumRec'''([[00998.htm|ULONG]]) Maximum number of records per buffer. (This is valid only for split streams).





=== SPCB Field - ulBlockSize ===

'''ulBlockSize'''([[00998.htm|ULONG]]) This field can be interpreted in two ways. If the SPCBBUF_INTERLEAVED flag is set, then this field is interpreted as the size of the I/O read operation. This is used to request a read buffer of a smaller size than the ''ulBufSize''field. The source stream handler will take the buffer of ''ulBufSize''and break up the actual I/O reads into ''ulBlockSize''chunks. If ''ulBlockSize''is 1, then the ''ulBufSize''is used as the default I/O read buffer size. Otherwise, ''ulBlockSize''will be the I/O read buffer size. The ''ulBufSize''value must be a multiple of the ''ulBlockSize''value.

The second interpretation of this field is for non-interleaved streams, when the SPCBBUF_INTERLEAVED is not set. The ''ulBlockSize''field represents the atom size of a data item. For example, for digital audio data type PCM 16-bit stereo at a 44.1KB sampling rate, the block size is 4 bytes.





=== SPCB Field - ulBufSize ===

'''ulBufSize'''([[00998.htm|ULONG]]) Size of buffer to be used while streaming. Maximum buffer size is 64KB.





=== SPCB Field - ulMinBuf ===

'''ulMinBuf'''([[00998.htm|ULONG]]) Minimum number of buffers needed to maintain a constant data stream.





=== SPCB Field - ulMaxBuf ===

'''ulMaxBuf'''([[00998.htm|ULONG]]) Maximum (ideal) number of buffers needed. For normal streams, this means the number of buffers that are allocated for the stream . For user-provided buffer streaming, this means the number of buffers that the Sync/Stream Manager can queue for a consumer. This can be used by a source stream handler that gives the same set of buffers to the Sync/Stream Manager repeatedly. If the number of buffers is set to the number of buffers in the set -1, the source stream handler will be able to detect when the target has consumed a buffer so it can be reused. It is assumed that the set of buffers is an ordered set and each buffer is used in the same order each time.





=== SPCB Field - ulSrcStart ===

'''ulSrcStart'''([[00998.htm|ULONG]]) Number of ''empty''buffers required to start the source stream handler. The value must be at least as big as the maximum number of buffers that would be requested by the source stream handler.





=== SPCB Field - ulTgtStart ===

'''ulTgtStart'''([[00998.htm|ULONG]]) Number of ''full''buffers required to start the target stream handler. The value must be at least as big as the maximum number of buffers that would be requested by the target stream handler. Usually, a target requires at least two buffers at the start of the stream.





=== SPCB Field - ulBufFlags ===

'''ulBufFlags'''([[00998.htm|ULONG]]) Buffer attributes (that is, the user provides buffers, fixed block size, interleaved data type, maximum buffer size).

SPCBBUF_16MEG The stream buffers can be allocated above the 16MB line. This is used by stream handler device drivers that can support greater than 16MB addresses.

SPCBBUF_FIXEDBUF The buffer size for this stream handler must be a particular fixed size (for this data type). The SPCBBUF_INTERLEAVED flag ( split stream) implies SPCBBUF_FIXEDBUF.

SPCBBUF_INTERLEAVED This is a split stream. It consists of one input stream of interleaved data that is split into multiple streams of individual data types. Only the source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_USERPROVIDED flag. SPCBBUF _FIXEDBUF cannot be used with this flag set.

SPCBBUF_MAXSIZE The ''ulBufSize''field contains the maximum size buffer that this stream handler can handle.

SPCBBUF_NONCONTIGUOUS Each data buffer is allocated contiguously in physical memory unless both stream handlers set the non-contiguous flag ( SPCBBUF_NONCONTIGUOUS). This flag provides the system flexibility in allocating memory. A device driver stream handler might require contiguous memory, while a DLL stream handler might not.

SPCBBUF_USERPROVIDED The user provides buffers for streaming. The Sync/ Stream Manager does not allocate buffers but attempts to lock down user- provided buffers or copy the data to locked buffers. Using this flag affects the performance of streaming. Only a source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_INTERLEAVED flag.





=== SPCB Field - ulHandFlags ===

'''ulHandFlags'''([[00998.htm|ULONG]]) Stream handler flags (that is, handlers can generate/ receive sync pulses, use the Sync/Stream Manager timer as master, and use the non-streaming handler as a NULL handler).

SPCBHAND_GENSYNC This stream handler can generate sync pulses.

SPCBHAND_GENTIME This stream handler can keep track of the real stream time . This handler also supports the SpiGetTime function and cue point events.

SPCBHAND_NOPREROLL This stream handler cannot preroll its device (that is, for recording streams, the source stream handler cannot be prerolled). If asked to preroll this stream, the Sync/Stream Manager treats this stream as if it were prerolled.

SPCBHAND_NONSTREAM This stream handler is a non-streaming handler (that is, it is a stream handler that can participate in synchronization but does not stream).

SPCBHAND_NOSYNC This stream handler can be in a sync group but does not receive or generate sync pulses. (It is useful to group streams so that they can be manipulated as a group).

SPCBHAND_PHYS_SEEK This stream handler does a seek to a physical device. Other stream handlers adjust stream time only on a seek request. The Sync/ Stream Manager always calls this stream handler first in an SpiSeekStream call.

SPCBHAND_RCVSYNC This stream handler can receive sync pulses.

SPCBHAND_TIMER This stream handler or the device (driver) it communicates with cannot support generation of sync pulses on a granularity necessary for synchronization. Therefore, use the stream manager sync timer as the master timer in a sync group.





=== SPCB Field - mmtimeTolerance ===

'''mmtimeTolerance'''([[00941.htm|MMTIME]]) It is used to determine whether to send a sync pulse to a specific slave stream handler.





=== SPCB Field - mmtimeSync ===

'''mmtimeSync'''([[00941.htm|MMTIME]]) Time interval in ''Chinatown units''between sync pulses. Used to save sync pulse generation granularity if this stream handler is a master but cannot generate its own sync pulse.





=== SPCB Field - ulBytesPerUnit ===

'''ulBytesPerUnit'''([[00998.htm|ULONG]]) Bytes per unit of time. This is used to do a seek on linear data that is not compressed or of variable length. Also used for SHC_GET_TIME queries in a stream handler.





=== SPCB Field - mmtimePerUnit ===

'''mmtimePerUnit'''([[00941.htm|MMTIME]]) The amount of MMTIME each unit represents. This also is used for the SHC_SEEK and SHC_GETTIME messages.





=== SPCBKEY ===

This structure identifies a stream protocol.

<pre class="western">typedef struct _SPCBKEY {
  ULONG     ulDataType;     /*  Data type for streaming operation. */
  ULONG     ulDataSubType;  /*  Data subtype. */
  ULONG     ulIntKey;       /*  Internal key. */
} SPCBKEY;

typedef   SPCBKEY   FAR   * PSPCBKEY ; </pre>




=== SPCBKEY Field - ulDataType ===

'''ulDataType'''([[00998.htm|ULONG]]) Data type for streaming operation. Primary descriptor of the data that will be used in the stream. Possible values can be found in OS2MEDEF.H.





=== SPCBKEY Field - ulDataSubType ===

'''ulDataSubType'''([[00998.htm|ULONG]]) Secondary descriptor of the data that will be used in the stream.





=== SPCBKEY Field - ulIntKey ===

'''ulIntKey'''([[00998.htm|ULONG]]) Contains a unique value used to identify one of several stream protocols of the same data type and subtype.





=== STATUS_PARM ===

This data structure contains fields for the ''pStatus''and ''ulStatusSize''fields of the [[00798.htm|DDCMDSTATUS]]data structure.

<pre class="western">typedef struct _STATUS_PARM {
  ULONG     ulTime;  /*  Current position time in milliseconds. */
} STATUS_PARM;
</pre>




=== STATUS_PARM Field - ulTime ===

'''ulTime'''([[00998.htm|ULONG]]) Specifies the current position time in milliseconds.





=== SZ ===

Null-terminated string (also known as a zero-terminated string).

<pre class="western">typedef CHAR SZ[];</pre>




=== ULONG ===

32-bit unsigned integer in the range 0 through 4 294 967 295.

<pre class="western">typedef unsigned long ULONG;</pre>




=== USHORT ===

Unsigned integer in the range 0 through 65 535.

<pre class="western">typedef unsigned short USHORT;</pre>




=== VCACAPISIZE ===



<pre class="western">typedef struct _VCACAPISIZE {
  ULONG     X_Left;
  ULONG     Y_Top;
  ULONG     Y_Height;
  ULONG     X_Width;
  ULONG     ScaleFactor;
} VCACAPISIZE;

typedef   VCACAPISIZE   FAR   *   PVCACAPISIZE ; </pre>




=== VCACAPISIZE Field - X_Left ===

'''X_Left'''([[00998.htm|ULONG]])





=== VCACAPISIZE Field - Y_Top ===

'''Y_Top'''([[00998.htm|ULONG]])





=== VCACAPISIZE Field - Y_Height ===

'''Y_Height'''([[00998.htm|ULONG]])





=== VCACAPISIZE Field - X_Width ===

'''X_Width'''([[00998.htm|ULONG]])





=== VCACAPISIZE Field - ScaleFactor ===

'''ScaleFactor'''([[00998.htm|ULONG]])





=== VCADEVINFO ===



<pre class="western">typedef struct _vcadevinfo {
  ULONG      Length;           /*  Length of structure. */
  CHAR       ProdInfo[30];     /*  Describes product information. */
  CHAR       ManInfo[30];      /*  Describes manufacturer information. */
  CHAR       Version[10];      /*  Describes version information. */
  ULONG      ImgFormat;        /*  Image format supported by the card. */
  USHORT     BitsPerPEL;       /*  Bits per pel in this image format. */
  USHORT     Overlay;          /*  Device has overlay support. */
  ULONG      Brightness;       /*  Default brightness value. */
  ULONG      hue;              /*  Default hue value. */
  ULONG      saturation;       /*  Default saturation value. */
  ULONG      contrast;         /*  Default contrast value. */
  ULONG      Sharpness;        /*  Default sharpness value. */
  ULONG      unused1;          /*  Reserved. */
  ULONG      S_X_Left;         /*  Source frame:  default left coordinate. */
  ULONG      S_Y_Top;          /*  Source frame:  default top coordinate. */
  ULONG      S_Y_Height;       /*  Source frame:  default height coordinate. */
  ULONG      S_X_Width;        /*  Source frame:  default width coordinate. */
  ULONG      D_X_Left;         /*  Destination frame:  default left coordinate. */
  ULONG      D_Y_Top;          /*  Destination frame:  default top coordinate. */
  ULONG      D_Y_Height;       /*  Destination frame:  default height coordinate. */
  ULONG      D_X_Width;        /*  Destination frame:  default width coordinate. */
  ULONG      D_ScaleFactor;
  ULONG      S_X_MAX;          /*  Maximum X size for the digitized source. */
  ULONG      S_Y_MAX;          /*  Maximum Y size for the digitized source. */
  ULONG      D_X_MAX;          /*  Maximum X size for the destination. */
  ULONG      D_Y_MAX;          /*  Maximum Y size for the destination. */
  ULONG      O_X_MAX;          /*  Maximum X size for the overlay destination. */
  ULONG      O_Y_MAX;          /*  Maximum Y size for the overlay destination. */
  USHORT     VideoInputs;      /*  Number of software switchable video inputs. */
  USHORT     CanRestore;       /*  Can restore an image on the device. */
  USHORT     CanStretch;       /*  Can scale image from source to destination. */
  USHORT     CanDistort;       /*  Can scale image without maintaining aspect ratio. */
  USHORT     HasVolume;        /*  Video device has volume control. */
  USHORT     HasBalance;       /*  Video device has balance control. */
  USHORT     CanScale;         /*  Can scale down source image on GetImage IOCtl. */
  USHORT     CanStream;        /*  Can do streaming of images to stream handler. */
  ULONG      DI_ulFilenum;     /*  File number associated with this instance/open of the device. */
  BYTE       HasTuner;         /*  Card has a channel tuner. */
  BYTE       HasTeleTex;       /*  Card has teletex support. */
  LONG       Delay_Time;       /*  Delay (ms) between connector change/query signal. */
  BYTE       HasAFC;           /*  Automatic Frequency Control/FineTune. */
  BYTE       HasPolarization;  /*  Support video frequency polarization. */
} VCADEVINFO;

typedef   VCADEVINFO   FAR   *   PVCADEVINFO ; </pre>




=== VCADEVINFO Field - Length ===

'''Length'''([[00998.htm|ULONG]]) Specifies the length, in bytes, of this structure.





=== VCADEVINFO Field - ProdInfo[30] ===

'''ProdInfo[30]'''([[00753.htm|CHAR]]) String describing product information.





=== VCADEVINFO Field - ManInfo[30] ===

'''ManInfo[30]'''([[00753.htm|CHAR]]) String describing manufacturer information.





=== VCADEVINFO Field - Version[10] ===

'''Version[10]'''([[00753.htm|CHAR]]) String describing version information.





=== VCADEVINFO Field - ImgFormat ===

'''ImgFormat'''([[00998.htm|ULONG]]) Indicates image format supported by the card. Valid image formats are:

DI_IMAGEFORMAT_RGB_565 5 bits of red, 6 bits of green, 5 bits of blue.

DI_IMAGEFORMAT_YUV_411 YUV_411 bit-interleaved format.





=== VCADEVINFO Field - BitsPerPEL ===

'''BitsPerPEL'''([[00999.htm|USHORT]]) Specifies bits per pel in this image format.





=== VCADEVINFO Field - Overlay ===

'''Overlay'''([[00999.htm|USHORT]]) Specifies if the device has overlay support (TRUE or FALSE ).





=== VCADEVINFO Field - Brightness ===

'''Brightness'''([[00998.htm|ULONG]]) Specifies the default brightness value (0 to 255).





=== VCADEVINFO Field - hue ===

'''hue'''([[00998.htm|ULONG]]) Specifies the default hue value (0 to 255).





=== VCADEVINFO Field - saturation ===

'''saturation'''([[00998.htm|ULONG]]) Specifies the default saturation value (0 to 255).





=== VCADEVINFO Field - contrast ===

'''contrast'''([[00998.htm|ULONG]]) Specifies the default contrast value (0 to 255).





=== VCADEVINFO Field - Sharpness ===

'''Sharpness'''([[00998.htm|ULONG]]) Specifies the default sharpness value (0 to 255).





=== VCADEVINFO Field - unused1 ===

'''unused1'''([[00998.htm|ULONG]]) Reserved. Set to zero.





=== VCADEVINFO Field - S_X_Left ===

'''S_X_Left'''([[00998.htm|ULONG]]) Specifies the default source frame default left coordinate .





=== VCADEVINFO Field - S_Y_Top ===

'''S_Y_Top'''([[00998.htm|ULONG]]) Specifies the default source frame default top coordinate.





=== VCADEVINFO Field - S_Y_Height ===

'''S_Y_Height'''([[00998.htm|ULONG]]) Specifies the default source frame default height coordinate.





=== VCADEVINFO Field - S_X_Width ===

'''S_X_Width'''([[00998.htm|ULONG]]) Specifies the default source frame default width coordinate.





=== VCADEVINFO Field - D_X_Left ===

'''D_X_Left'''([[00998.htm|ULONG]]) Specifies the default destination frame default left coordinate.





=== VCADEVINFO Field - D_Y_Top ===

'''D_Y_Top'''([[00998.htm|ULONG]]) Specifies the default destination frame default top coordinate.





=== VCADEVINFO Field - D_Y_Height ===

'''D_Y_Height'''([[00998.htm|ULONG]]) Specifies the default destination frame default height coordinate.





=== VCADEVINFO Field - D_X_Width ===

'''D_X_Width'''([[00998.htm|ULONG]]) Specifies the default destination frame default width coordinate.





=== VCADEVINFO Field - D_ScaleFactor ===

'''D_ScaleFactor'''([[00998.htm|ULONG]]) Specifies the default scale factor on a copy action.





=== VCADEVINFO Field - S_X_MAX ===

'''S_X_MAX'''([[00998.htm|ULONG]]) Indicates the maximum X size for the digitized source.





=== VCADEVINFO Field - S_Y_MAX ===

'''S_Y_MAX'''([[00998.htm|ULONG]]) Indicates the maximum Y size for the digitized source.





=== VCADEVINFO Field - D_X_MAX ===

'''D_X_MAX'''([[00998.htm|ULONG]]) Indicates the maximum X size for the destination.





=== VCADEVINFO Field - D_Y_MAX ===

'''D_Y_MAX'''([[00998.htm|ULONG]]) Indicates the maximum Y size for the destination.





=== VCADEVINFO Field - O_X_MAX ===

'''O_X_MAX'''([[00998.htm|ULONG]]) Indicates the maximum X size for the overlay destination.





=== VCADEVINFO Field - O_Y_MAX ===

'''O_Y_MAX'''([[00998.htm|ULONG]]) Indicates the maximum Y size for the overlay destination.





=== VCADEVINFO Field - VideoInputs ===

'''VideoInputs'''([[00999.htm|USHORT]]) Specifies the number of software switchable video inputs.





=== VCADEVINFO Field - CanRestore ===

'''CanRestore'''([[00999.htm|USHORT]]) Indicates if an image can be restored on the device (0= VCAI Play not supported; 1=VCAI Play supported-Start and Data only; 3=VCAI Play supported-Pause/Stop/Flush also supported).





=== VCADEVINFO Field - CanStretch ===

'''CanStretch'''([[00999.htm|USHORT]]) Indicates if the image can be scaled from source to destination (TRUE or FALSE).





=== VCADEVINFO Field - CanDistort ===

'''CanDistort'''([[00999.htm|USHORT]]) Indicates if the image can be scaled without maintaining aspect ratio (TRUE or FALSE).





=== VCADEVINFO Field - HasVolume ===

'''HasVolume'''([[00999.htm|USHORT]]) Indicates if the video device has volume control (TRUE or FALSE).





=== VCADEVINFO Field - HasBalance ===

'''HasBalance'''([[00999.htm|USHORT]]) Indicates if the video device has balance control (TRUE or FALSE).





=== VCADEVINFO Field - CanScale ===

'''CanScale'''([[00999.htm|USHORT]]) Indicates if the image can be scaled down on GetImage IOCtl (TRUE or FALSE).





=== VCADEVINFO Field - CanStream ===

'''CanStream'''([[00999.htm|USHORT]]) Indicates if the device supports streaming of images to stream handler (TRUE or FALSE).





=== VCADEVINFO Field - DI_ulFilenum ===

'''DI_ulFilenum'''([[00998.htm|ULONG]]) This file number is used to associate the stream creation with a particular open instance.





=== VCADEVINFO Field - HasTuner ===

'''HasTuner'''([[00752.htm|BYTE]]) Card has a channel tuner.





=== VCADEVINFO Field - HasTeleTex ===

'''HasTeleTex'''([[00752.htm|BYTE]]) Card has teletex support.





=== VCADEVINFO Field - Delay_Time ===

'''Delay_Time'''([[00816.htm|LONG]]) Delay (ms) between connector change/query signal.





=== VCADEVINFO Field - HasAFC ===

'''HasAFC'''([[00752.htm|BYTE]]) Automatic Frequency Control/FineTune.





=== VCADEVINFO Field - HasPolarization ===

'''HasPolarization'''([[00752.htm|BYTE]]) Support video frequency polarization.





=== VCAEDCOLORKEY ===



<pre class="western">typedef struct _VCAEDCOLORKEY {
  BOOL     bColorKeying;  /*  1=TRUE=ON, 0=FALSE=OFF. */
} VCAEDCOLORKEY;

typedef   VCAEDCOLORKEY   FAR   *   PVCAEDCOLORKEY ; </pre>




=== VCAEDCOLORKEY Field - bColorKeying ===

'''bColorKeying'''([[00751.htm|BOOL]]) 1=TRUE=ON, 0=FALSE=OFF.





=== VCAGETIMAGESCALE ===



<pre class="western">typedef struct _VCAGETIMAGESCALE {
  ULONG     Capture_Buf_Len;  /*  Length, in bytes, of capture buffer. */
  ULONG     Capture_Buf_Ptr;  /*  Pointer to the capture buffer. */
  ULONG     Source_X_Left;    /*  Leftmost pel offset in source frame. */
  ULONG     Source_Y_Top;     /*  Topmost pel offset in source frame. */
  ULONG     Source_Y_Height;  /*  Height of source frame, in pels. */
  ULONG     Source_X_Width;   /*  Width of source frame, in pels. */
  ULONG     Dest_X_Left;      /*  Destination frame's left transpose offset. */
  ULONG     Dest_Y_Top;       /*  Destination frame's top transpose offset. */
  ULONG     Dest_Y_Height;    /*  Height of destination frame in pels. */
  ULONG     Dest_X_Width;     /*  Width of destination frame in pels. */
} VCAGETIMAGESCALE;

typedef   VCAGETIMAGESCLAE   FAR   *   PVCAGETIMAGESCALE ; </pre>




=== VCAGETIMAGESCALE Field - Capture_Buf_Len ===

'''Capture_Buf_Len'''([[00998.htm|ULONG]]) Specifies the length, in bytes, of the capture buffer.





=== VCAGETIMAGESCALE Field - Capture_Buf_Ptr ===

'''Capture_Buf_Ptr'''([[00998.htm|ULONG]]) Specifies a pointer to the capture buffer.





=== VCAGETIMAGESCALE Field - Source_X_Left ===

'''Source_X_Left'''([[00998.htm|ULONG]]) Specifies the leftmost pel offset in the source frame .





=== VCAGETIMAGESCALE Field - Source_Y_Top ===

'''Source_Y_Top'''([[00998.htm|ULONG]]) Specifies the topmost pel offset in the source frame.





=== VCAGETIMAGESCALE Field - Source_Y_Height ===

'''Source_Y_Height'''([[00998.htm|ULONG]]) Specifies the height of the source frame, in pels.





=== VCAGETIMAGESCALE Field - Source_X_Width ===

'''Source_X_Width'''([[00998.htm|ULONG]]) Specifies the width of the source frame, in pels.





=== VCAGETIMAGESCALE Field - Dest_X_Left ===

'''Dest_X_Left'''([[00998.htm|ULONG]]) Specifies the destination frame's left transpose offset .





=== VCAGETIMAGESCALE Field - Dest_Y_Top ===

'''Dest_Y_Top'''([[00998.htm|ULONG]]) Specifies the destination frame's top transpose offset.





=== VCAGETIMAGESCALE Field - Dest_Y_Height ===

'''Dest_Y_Height'''([[00998.htm|ULONG]]) Specifies the height of the destination frame in pels .





=== VCAGETIMAGESCALE Field - Dest_X_Width ===

'''Dest_X_Width'''([[00998.htm|ULONG]]) Specifies the width of the destination frame in pels.





=== VCALOAD ===

This structure contains fields for the [[00629.htm|VCAI_LOAD_MICROCODE]]function.

<pre class="western">typedef struct _VCALOAD {
  ULONG     ulflags;        /*  1=Query, 2=Load, 3=Unload. */
  CHAR      ProdInfo[256];  /*  Path and name of microcode load. */
  LONG      ulLoadID;       /*  Load ID (returned on Load, sent on Unload). */
  ULONG     ulLength;       /*  Length of load data (sent on Load). */
  PVOID     pLoadData;      /*  Pointer to microcode load data (sent on Load). */
} VCALOAD;

typedef   VCALOAD   FAR   *   PVCALOAD ; </pre>




=== VCALOAD Field - ulflags ===

'''ulflags'''([[00998.htm|ULONG]]) The following flags are defined.

<pre class="western">VCALOAD_QUERY     0x01
VCALOAD_LOAD      0x02
VCALOAD_UNLOAD    0x03</pre>






=== VCALOAD Field - ProdInfo[256] ===

'''ProdInfo[256]'''([[00753.htm|CHAR]]) If a drive letter (like C:) is not included, the MMPM/ 2 subsystem appends the MMPM/2 base directory (usually &quot;C:/MMOS2/&quot;) to the name returned.





=== VCALOAD Field - ulLoadID ===

'''ulLoadID'''([[00816.htm|LONG]]) Load ID (returned on Load, sent on Unload).





=== VCALOAD Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of load data (sent on Load).





=== VCALOAD Field - pLoadData ===

'''pLoadData'''([[01203.htm|PVOID]]) Pointer to microcode load data (sent on Load).





=== VCAIMAGERF ===

This structure contains fields for the [[00635.htm|VCAI_RESTORE_FORMAT]]function.

<pre class="western">typedef struct _VCAIMAGERF {
  ULONG     ulFlags;       /*  0=Query, 1=Set. */
  ULONG     ulNumFormats;  /*  Number of supported formats. */
  ULONG     ulCurIndex;    /*  Current format (or format to set to). */
  ULONG     FourCC[64];    /*  Name of format. */
} VCAIMAGERF;

typedef   VCAIMAGERF   FAR   *   PVCAIMAGERF ; </pre>




=== VCAIMAGERF Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following values are defined for ''ulFlags''.

<pre class="western">VCAIRF_Query    0x00
VCAIRF_Set      0x01</pre>






=== VCAIMAGERF Field - ulNumFormats ===

'''ulNumFormats'''([[00998.htm|ULONG]]) Number of supported formats.





=== VCAIMAGERF Field - ulCurIndex ===

'''ulCurIndex'''([[00998.htm|ULONG]]) Current format (or format to set to).





=== VCAIMAGERF Field - FourCC[64] ===

'''FourCC[64]'''([[00998.htm|ULONG]]) Name of format.





=== VCAIMAGECF ===

This structure contains fields for the [[00641.htm|VCAI_CAPTURE_FORMAT]]function.

<pre class="western">typedef struct _VCAIMAGECF {
  ULONG     ulFlags;       /*  0=Query, 1=Set. */
  ULONG     ulNumFormats;  /*  Number of supported formats. */
  ULONG     ulCurIndex;    /*  Current format (or format to set to). */
  ULONG     FourCC[64];    /*  Name of format. */
} VCAIMAGECF;

typedef   VCAIMAGECF   FAR   *   PVCAIMAGECF ; </pre>




=== VCAIMAGECF Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following values are defined for ''ulFlags''.

<pre class="western">VCAICF_Query   0x00
VCAICF_Set     0x01</pre>






=== VCAIMAGECF Field - ulNumFormats ===

'''ulNumFormats'''([[00998.htm|ULONG]]) Number of supported formats.





=== VCAIMAGECF Field - ulCurIndex ===

'''ulCurIndex'''([[00998.htm|ULONG]]) Current format (or format to set to).





=== VCAIMAGECF Field - FourCC[64] ===

'''FourCC[64]'''([[00998.htm|ULONG]]) Name of format.





=== VCASETCAPTURERECT ===



<pre class="western">typedef struct _VCASETCAPTURERECT {
  ULONG     Source_X_Left;    /*  Leftmost pel offset in source frame. */
  ULONG     Source_Y_Top;     /*  Topmost pel offset in source frame. */
  ULONG     Source_Y_Height;  /*  Height of source frame, in pels. */
  ULONG     Source_X_Width;   /*  Width of source frame, in pels. */
  ULONG     Dest_X_Left;      /*  Destination frame's left transpose offset. */
  ULONG     Dest_Y_Top;       /*  Destination frame's top transpose offset. */
  ULONG     Dest_Y_Height;    /*  Height of destination frame in pels. */
  ULONG     Dest_X_Width;     /*  Width of destination frame in pels. */
} VCASETCAPTURERECT;

typedef   VCASETCAPTURERECT   FAR   *   PVCASETCAPTURERECT ; </pre>




=== VCASETCAPTURERECT Field - Source_X_Left ===

'''Source_X_Left'''([[00998.htm|ULONG]]) Specifies the leftmost pel offset in the source frame .





=== VCASETCAPTURERECT Field - Source_Y_Top ===

'''Source_Y_Top'''([[00998.htm|ULONG]]) Specifies the topmost pel offset in the source frame.





=== VCASETCAPTURERECT Field - Source_Y_Height ===

'''Source_Y_Height'''([[00998.htm|ULONG]]) Specifies the height of source frame, in pels.





=== VCASETCAPTURERECT Field - Source_X_Width ===

'''Source_X_Width'''([[00998.htm|ULONG]]) Specifies the width of source frame, in pels.





=== VCASETCAPTURERECT Field - Dest_X_Left ===

'''Dest_X_Left'''([[00998.htm|ULONG]]) Specifies the destination frame's left transpose offset .





=== VCASETCAPTURERECT Field - Dest_Y_Top ===

'''Dest_Y_Top'''([[00998.htm|ULONG]]) Specifies the destination frame's top transpose offset.





=== VCASETCAPTURERECT Field - Dest_Y_Height ===

'''Dest_Y_Height'''([[00998.htm|ULONG]]) Specifies the height of the destination frame in pels .





=== VCASETCAPTURERECT Field - Dest_X_Width ===

'''Dest_X_Width'''([[00998.htm|ULONG]]) Specifies the width of the destination frame in pels.





=== VCASETCOLORKEY ===



<pre class="western">typedef struct _VCASETCOLORKEY {
  ULONG     ulColorKey;  /*  Transparent color. */
} VCASETCOLORKEY;

typedef   VCASETCOLORKEY   FAR   *   PVCASETCOLORKEY ; </pre>




=== VCASETCOLORKEY Field - ulColorKey ===

'''ulColorKey'''([[00998.htm|ULONG]]) VCASETCOLORKEY value is based on the number of colors supported by the display driver. When in palletized mode (less than or equal to 256 colors), VCASETCOLORKEY is a palette index; when in 16-bit color mode, VCASETCOLORKEY is an RGB-565 color; when in 24-bit color mode, VCASETCOLORKEY is an RGB-888 color.





=== VCASETFPS ===

This structure contains fields for the [[00715.htm|VCAI_SETFPS]]function.

<pre class="western">typedef struct _VCASETFPS {
  ULONG     set_FPS;  /*  Frames per second to stream. */
  ULONG     ulFlags;  /*  Frames or microseconds. */
} VCASETFPS;

typedef   VCASETFPS   FAR   *   PVCASETFPS ; </pre>




=== VCASETFPS Field - set_FPS ===

'''set_FPS'''([[00998.htm|ULONG]]) Frames per second unless the ulFlags field is set to VCASF_ MICROSECONDS-then, the field becomes microseconds per frame.





=== VCASETFPS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following ''ulFlags''are defined:

<pre class="western">VCASF_FRAMES        0x0
VCASF_MICROSECONDS  0x1</pre>






=== VCASETMONITOR ===



<pre class="western">typedef struct _VCASETMONITOR {
  BOOL     bMonitor;  /*  1=TRUE=ON, 0=FALSE=OFF. */
} VCASETMONITOR;

typedef   VCASETMONITOR   FAR   *   PVCASETMONITOR ; </pre>




=== VCASETMONITOR Field - bMonitor ===

'''bMonitor'''([[00751.htm|BOOL]]) 1=TRUE=ON, 0=FALSE=OFF.





=== VCASETVIDEO ===



<pre class="western">typedef struct _VCASETVIDEO {
  ULONG     set_brightness;  /*  New overall image brightness setting. */
  ULONG     set_hue;         /*  New image hue (color) setting. */
  ULONG     set_saturation;  /*  New color intensity setting. */
  ULONG     set_contrast;    /*  New contrast setting. */
  ULONG     ret_brightness;  /*  Current overall image brightness setting. */
  ULONG     ret_hue;         /*  Current image hue (color) setting. */
  ULONG     ret_saturation;  /*  Current color intensity setting. */
  ULONG     ret_contrast;    /*  Current contrast setting. */
} VCASETVIDEO;

typedef   VCASETVIDEO   FAR   *   PVCASETVIDEO ; </pre>




=== VCASETVIDEO Field - set_brightness ===

'''set_brightness'''([[00998.htm|ULONG]]) Specifies the new overall image brightness setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.





=== VCASETVIDEO Field - set_hue ===

'''set_hue'''([[00998.htm|ULONG]]) Specifies the new image hue (color) setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.





=== VCASETVIDEO Field - set_saturation ===

'''set_saturation'''([[00998.htm|ULONG]]) Specifies the new saturation (color intensity) setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.





=== VCASETVIDEO Field - set_contrast ===

'''set_contrast'''([[00998.htm|ULONG]]) Specifies the new luminance contrast setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.





=== VCASETVIDEO Field - ret_brightness ===

'''ret_brightness'''([[00998.htm|ULONG]]) Specifies the current overall image brightness setting. Valid values are 0 to 255 or NOT_SUPPORTED.





=== VCASETVIDEO Field - ret_hue ===

'''ret_hue'''([[00998.htm|ULONG]]) Specifies the current image hue (color) setting. Valid values are 0 to 255 or NOT_SUPPORTED.





=== VCASETVIDEO Field - ret_saturation ===

'''ret_saturation'''([[00998.htm|ULONG]]) Specifies the current color intensity setting. Valid values are 0 to 255 or NOT_SUPPORTED.





=== VCASETVIDEO Field - ret_contrast ===

'''ret_contrast'''([[00998.htm|ULONG]]) Specifies the current luminance contrast setting. Valid values are 0 to 255 or NOT_SUPPORTED.





=== VCASETVIDEOINPUT ===



<pre class="western">typedef struct _VCASETVIDEOINPUT {
  ULONG     INPUT_CONNECTOR;  /*  Connector value. */
} VCASETVIDEOINPUT;

typedef   VCASETVIDEOINPUT   FAR   *   PVCASETVIDEOINPUT ; </pre>




=== VCASETVIDEOINPUT Field - INPUT_CONNECTOR ===

'''INPUT_CONNECTOR'''([[00998.htm|ULONG]]) Sets or queries the input connector value. A value of -1 performs a query and returns the current connector value. A value of -2 sets the video input source connector to the default value.





=== VCASTREAM ===

This structure contains fields for the [[00647.htm|VCAI_PLAY]]function.

<pre class="western">typedef struct _VCASTREAM {
  ULONG     ulLength;     /*  Length of image data. */
  PVOID     pImageData;   /*  Pointer to image data. */
  ULONG     ulFlags;      /*  Flag information. */
  ULONG     ulSCR;        /*  MPEG system clock reference (SCR). */
  ULONG     ulPTS;        /*  MPEG presentation time stamp (PTS). */
  ULONG     ulAudioTime;  /*  Current audio stream time. */
} VCASTREAM;

typedef   VCASTREAM   FAR   *   PVCASTREAM ; </pre>




=== VCASTREAM Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of image data.





=== VCASTREAM Field - pImageData ===

'''pImageData'''([[01203.htm|PVOID]]) Pointer to image data.





=== VCASTREAM Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following flags are defined.

<pre class="western">VCA_PLAY_START     0x01
VCA_PLAY_DATA      0x02
VCA_PLAY_STOP      0x04
VCA_PLAY_FLUSH     0x08
VCA_PLAY_PAUSE</pre>






=== VCASTREAM Field - ulSCR ===

'''ulSCR'''([[00998.htm|ULONG]]) MPEG system clock reference (SCR). Set to 0 if current packet does not contain a SCR. CODEC-specific, currently used only in split-stream MPEG playback.





=== VCASTREAM Field - ulPTS ===

'''ulPTS'''([[00998.htm|ULONG]]) MPEG presentation time stamp (PTS). Set to 0 if current packet does not contain a PTS. CODEC-specific, currently used only in split -stream MPEG playback.





=== VCASTREAM Field - ulAudioTime ===

'''ulAudioTime'''([[00998.htm|ULONG]]) Current audio stream time is in MMTIME format on VCA_ PLAY_DATA and in MPEG-90kHz format on VCA_PLAY_START. CODEC-specific, currently used only in split-stream MPEG playback.





=== VCATUNCHAN ===

This structure contains fields for the [[00659.htm|VCAI_TUNERCHANNEL]]function.

<pre class="western">typedef struct _VCATUNCHAN {
  ULONG      ulFlags;      /*  1=Set, 2=Query. */
  ULONG      ulOptions;    /*  Options. */
  USHORT     usResv01;     /*  Reserved. */
  USHORT     usResv02;     /*  Reserved. */
  LONG       lFineTune;    /*  Fine tune value for channel. */
  ULONG      ulFrequency;  /*  Frequency instead of channel/region. */
} VCATUNCHAN;

typedef   VCATUNCHAN   FAR   *   PVCATUNCHAN ; </pre>




=== VCATUNCHAN Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) The following flags are defined.

<pre class="western">TUC_SET_CHANNEL    1
TUC_QUERY_CHANNEL  2</pre>






=== VCATUNCHAN Field - ulOptions ===

'''ulOptions'''([[00998.htm|ULONG]]) The ''ulOptions''field is a bit-sensitive field. The following values are defined for ''ulOptions''.

<pre class="western">TUC_AFC_ON               4
TUC_AFC_OFF              0
TUC_FREQUENCY            8
TUC_CHANNEL              0
TUC_POLOARIZATION_VERT  16
TUC_POLOARIZATION_HORI  32</pre>






=== VCATUNCHAN Field - usResv01 ===

'''usResv01'''([[00999.htm|USHORT]]) Resv01 set to 0.





=== VCATUNCHAN Field - usResv02 ===

'''usResv02'''([[00999.htm|USHORT]]) Resv02 set to 0.





=== VCATUNCHAN Field - lFineTune ===

'''lFineTune'''([[00816.htm|LONG]]) Fine tune value for channel.





=== VCATUNCHAN Field - ulFrequency ===

'''ulFrequency'''([[00998.htm|ULONG]]) Frequency instead of channel/region.





=== VSD_AUDIOATTRIBUTES_PARMS ===

This structure contains fields for the [[00309.htm|VSD_QUERYAUDIOATTRIBUTES]]command.

<pre class="western">typedef struct _VSD_AUDIOATTRIBUTES_PARMS {
  ULONG     ulLength;  /*  Length of the structure. */
  ULONG     ulFlags;   /*  Attribute to set. */
  ULONG     ulValue;   /*  Input/Output.  Value for attribute setting. */
  ULONG     ulDelay;   /*  Input.  Delay for attribute setting. */
} VSD_AUDIOATTRIBUTES_PARMS;

typedef   VSD _ AUDIOATTRIBUTES _ PARMS   * PVSD _ AUDIOATTRIBUTES _ PARMS ; </pre>




=== VSD_AUDIOATTRIBUTES_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== VSD_AUDIOATTRIBUTES_PARMS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Input. The following values are defined for ''ulFlags''.

VSD_BALANCE Set or query balance.

VSD_BASS Set or query bass.

VSD_GAIN Set or query gain.

VSD_TREBLE Set or query treble.

VSD_PITCH Set or query pitch.





=== VSD_AUDIOATTRIBUTES_PARMS Field - ulValue ===

'''ulValue'''([[00998.htm|ULONG]]) Input/Output. Value for attribute setting.





=== VSD_AUDIOATTRIBUTES_PARMS Field - ulDelay ===

'''ulDelay'''([[00998.htm|ULONG]]) Delay for attribute setting to take place in mmtime units.





=== VSD_AUDIODATATYPE_PARMS ===

This structure contains fields for the [[00290.htm|VSD_OPEN]]command.

<pre class="western">typedef struct _VSD_AUDIODATATYPE_PARMS {
  ULONG     ulLength;              /*  Length of the structure. */
  ULONG     ulFlags;               /*  Flags. */
  ULONG     ulSamplingRate;        /*  Input.  Sampling rate setting. */
  ULONG     ulBitsPerSample;       /*  Input.  Bits per sample setting. */
  ULONG     ulChannels;            /*  Input.  Channels setting. */
  ULONG     ulBlockAlignment;      /*  Output.  Block alignment. */
  ULONG     ulAverageBytesPerSec;  /*  Output.  Average bytes per second throughput. */
  ULONG     ulDataType;            /*  Input.  Data type to set or query. */
  ULONG     ulDataSubType;         /*  Output.  Data subtype info. */
  ULONG     ulReserved1;           /*  Reserved. */
  ULONG     ulOperation;           /*  Input.  VSD_PRODUCE or VSD_CONSUME. */
  ULONG     ulDeviceID;            /*  Input.  Device ID of the amp-mixer. */
  PVOID     pDevInfo;              /*  Device-specific information. */
} VSD_AUDIODATATYPE_PARMS;

typedef   VSD _ AUDIODATATYPE _ PARMS   * PVSD _ AUDIODATATYPE _ PARMS ; </pre>




=== VSD_AUDIODATATYPE_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== VSD_AUDIODATATYPE_PARMS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Flags indicating which fields are to be queried or modified . The VSD_AUDIODATATYPE_PARMS structure must contain at least one of the following flags.

'''Note:'''More than one flag can be specified.

VSD_MODE Set/query mode.

VSD_CHANNELS Set/query channels.

VSD_SAMPLESPERSEC Set/query sampling rate.

VSD_BITSPERSAMPLE Set/query bits per sample.

VSD_OPERATION Set/query VSD operation field.





=== VSD_AUDIODATATYPE_PARMS Field - ulSamplingRate ===

'''ulSamplingRate'''([[00998.htm|ULONG]]) Input. Sampling rate setting.





=== VSD_AUDIODATATYPE_PARMS Field - ulBitsPerSample ===

'''ulBitsPerSample'''([[00998.htm|ULONG]]) Input. Bits per sample setting.





=== VSD_AUDIODATATYPE_PARMS Field - ulChannels ===

'''ulChannels'''([[00998.htm|ULONG]]) Input. Channels setting.





=== VSD_AUDIODATATYPE_PARMS Field - ulBlockAlignment ===

'''ulBlockAlignment'''([[00998.htm|ULONG]]) Output. Block alignment.





=== VSD_AUDIODATATYPE_PARMS Field - ulAverageBytesPerSec ===

'''ulAverageBytesPerSec'''([[00998.htm|ULONG]]) Output. Average bytes per second throughput.





=== VSD_AUDIODATATYPE_PARMS Field - ulDataType ===

'''ulDataType'''([[00998.htm|ULONG]]) Input. Data type to set or query. This value is a RIFF datatype (such as DATATYPE_WAVEFORM) defined in OS2MEDEF.H.





=== VSD_AUDIODATATYPE_PARMS Field - ulDataSubType ===

'''ulDataSubType'''([[00998.htm|ULONG]]) Output. Data subtype info.





=== VSD_AUDIODATATYPE_PARMS Field - ulReserved1 ===

'''ulReserved1'''([[00998.htm|ULONG]]) Reserved.





=== VSD_AUDIODATATYPE_PARMS Field - ulOperation ===

'''ulOperation'''([[00998.htm|ULONG]]) Input. Operation to perform; set to either VSD_PRODUCE or VSD_CONSUME.





=== VSD_AUDIODATATYPE_PARMS Field - ulDeviceID ===

'''ulDeviceID'''([[00998.htm|ULONG]]) Input. Device ID of the amp-mixer.





=== VSD_AUDIODATATYPE_PARMS Field - pDevInfo ===

'''pDevInfo'''([[01203.htm|PVOID]]) Device-specific information.





=== VSD_AUDIOOPEN_PARMS ===

This structure contains fields for the [[00290.htm|VSD_OPEN]]command.

<pre class="western">typedef struct _VSD_AUDIOOPEN_PARMS {
  ULONG     ulLength;              /*  Input.  Length of the structure. */
  ULONG     ulFlags;               /*  Input.  Flags. */
  ULONG     ulSamplingRate;        /*  Input.  Sampling rate. */
  ULONG     ulBitsPerSample;       /*  Input.  Bits per sample. */
  ULONG     ulChannels;            /*  Input.  Channels. */
  ULONG     ulBlockAlignment;      /*  Input.  Block alignment. */
  ULONG     ulAverageBytesPerSec;  /*  Output.  Average bytes per second throughput. */
  ULONG     ulDataType;            /*  Input.  Data type to set or query. */
  ULONG     ulDataSubType;         /*  Output.  Data subtype info. */
  ULONG     hidSource;             /*  Input.  Source stream handler for VSD.  (Unused) */
  ULONG     hidTarget;             /*  Input.  Target stream handler for VSD.  (Unused) */
  ULONG     ulOperation;           /*  Input.  Operation to perform. */
  ULONG     ulReserved1;           /*  Reserved. */
  ULONG     ulDeviceID;            /*  Input.  Device ID of the amp-mixer. */
  PVOID     pHeader;               /*  Pointer to media-specific header. */
  PVOID     pParmString;           /*  Input.  Device-specific parm string. */
  PVOID     pDevInfo;              /*  Device-specific information. */
  ULONG     ulReserved2;           /*  Reserved. */
  PCHAR     pResourceDLL;          /*  Input.  Resource DLL from MMPM2.INI file. */
  ULONG     ulResourceId;          /*  Input.  Resource ID to use in Resource DLL. */
} VSD_AUDIOOPEN_PARMS;

typedef   VSD _ AUDIOOPEN _ PARMS   * PVSD _ AUDIOOPEN _ PARMS ; </pre>




=== VSD_AUDIOOPEN_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Input. Length of the structure.





=== VSD_AUDIOOPEN_PARMS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Input. Flags indicating which fields are to be queried or modified. (Unused)





=== VSD_AUDIOOPEN_PARMS Field - ulSamplingRate ===

'''ulSamplingRate'''([[00998.htm|ULONG]]) Input. Sampling rate.





=== VSD_AUDIOOPEN_PARMS Field - ulBitsPerSample ===

'''ulBitsPerSample'''([[00998.htm|ULONG]]) Input. Bits per sample.





=== VSD_AUDIOOPEN_PARMS Field - ulChannels ===

'''ulChannels'''([[00998.htm|ULONG]]) Input. Channels.





=== VSD_AUDIOOPEN_PARMS Field - ulBlockAlignment ===

'''ulBlockAlignment'''([[00998.htm|ULONG]]) Input. Block alignment. (Unused)





=== VSD_AUDIOOPEN_PARMS Field - ulAverageBytesPerSec ===

'''ulAverageBytesPerSec'''([[00998.htm|ULONG]]) Output. Average bytes per second throughput.





=== VSD_AUDIOOPEN_PARMS Field - ulDataType ===

'''ulDataType'''([[00998.htm|ULONG]]) Input. Data type to set or query.





=== VSD_AUDIOOPEN_PARMS Field - ulDataSubType ===

'''ulDataSubType'''([[00998.htm|ULONG]]) Output. Data subtype info.





=== VSD_AUDIOOPEN_PARMS Field - hidSource ===

'''hidSource'''([[00998.htm|ULONG]]) Input. Source stream handler for VSD. (Unused)





=== VSD_AUDIOOPEN_PARMS Field - hidTarget ===

'''hidTarget'''([[00998.htm|ULONG]]) Input. Target stream handler for VSD. (Unused)





=== VSD_AUDIOOPEN_PARMS Field - ulOperation ===

'''ulOperation'''([[00998.htm|ULONG]]) Input. Operation to perform. Defined values for ''ulOperation''include VSD_PRODUCE and VSD_CONSUME.





=== VSD_AUDIOOPEN_PARMS Field - ulReserved1 ===

'''ulReserved1'''([[00998.htm|ULONG]]) Reserved.





=== VSD_AUDIOOPEN_PARMS Field - ulDeviceID ===

'''ulDeviceID'''([[00998.htm|ULONG]]) Input. Device ID of the amp-mixer. This ID is necessary if media control interface calls must be made by the VSD.





=== VSD_AUDIOOPEN_PARMS Field - pHeader ===

'''pHeader'''([[01203.htm|PVOID]]) Pointer to media-specific header. For audio, it is an MMAUDIOHEADER. For further information, see the ''OS/2 Multimedia Programming Reference''. (Unused)





=== VSD_AUDIOOPEN_PARMS Field - pParmString ===

'''pParmString'''([[01203.htm|PVOID]]) Input. Pointer to device-specific parmstring in MMPM2. INI file.





=== VSD_AUDIOOPEN_PARMS Field - pDevInfo ===

'''pDevInfo'''([[01203.htm|PVOID]]) Device-specific information.





=== VSD_AUDIOOPEN_PARMS Field - ulReserved2 ===

'''ulReserved2'''([[00998.htm|ULONG]]) Reserved.





=== VSD_AUDIOOPEN_PARMS Field - pResourceDLL ===

'''pResourceDLL'''([[00753.htm|PCHAR]]) Input. Resource DLL from MMPM2.INI file. VSD can use this file to retrieve VSD-specific setup information.





=== VSD_AUDIOOPEN_PARMS Field - ulResourceId ===

'''ulResourceId'''([[00998.htm|ULONG]]) Input. Resource ID to use in Resource DLL.





=== VSD_CONNECTOR_PARMS ===

This structure contains fields for the [[00319.htm|VSD_QUERYCONNECTOR]]message.

<pre class="western">typedef struct _VSD_CONNECTOR_PARMS {
  ULONG     ulLength;     /*  Input.  Length of the structure. */
  ULONG     ulFlags;      /*  Flags to be queried or modified. */
  CHAR      ulConn_Type;  /*  Input.  Type of connector. */
  ULONG     ulIndex;      /*  Input.  Connector number. */
  BOOL      fEnabled;     /*  Input/Output.  Indicates enabled or disabled. */
} VSD_CONNECTOR_PARMS;

typedef   VSD _ CONNECTOR _ PARMS   * PVSD _ CONNECTOR _ PARMS ; </pre>




=== VSD_CONNECTOR_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Input. Length of the structure.





=== VSD_CONNECTOR_PARMS Field - ulFlags ===

'''ulFlags'''([[00998.htm|ULONG]]) Flags to be queried or modified.





=== VSD_CONNECTOR_PARMS Field - ulConn_Type ===

'''ulConn_Type'''([[00753.htm|CHAR]]) Input. Type of connector.





=== VSD_CONNECTOR_PARMS Field - ulIndex ===

'''ulIndex'''([[00998.htm|ULONG]]) Input. Connector number.





=== VSD_CONNECTOR_PARMS Field - fEnabled ===

'''fEnabled'''([[00751.htm|BOOL]]) Input. Indicates if connector is enabled or disabled.





=== VSD_ESCAPE_PARMS ===

This structure contains fields for the [[00274.htm|VSD_ESCAPE]]message.

<pre class="western">typedef struct _VSD_ESCAPE_PARMS {
  ULONG     ulLength;        /*  Length of the structure. */
  PVOID     pBuffer;         /*  Information for VSD. */
  ULONG     ulBufferLength;  /*  Length of pBuffer. */
} VSD_ESCAPE_PARMS;

typedef   VSD _ ESCAPE _ PARMS   * PVSD _ ESCAPE _ PARMS ; </pre>




=== VSD_ESCAPE_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.





=== VSD_ESCAPE_PARMS Field - pBuffer ===

'''pBuffer'''([[01203.htm|PVOID]]) Information to pass to the VSD.





=== VSD_ESCAPE_PARMS Field - ulBufferLength ===

'''ulBufferLength'''([[00998.htm|ULONG]]) Length of ''pBuffer''.





=== VSD_GETDEVCAPS_PARMS ===

This structure contains fields for the [[00264.htm|VSD_GETDEVCAPS]]message.

<pre class="western">typedef struct _VSD_GETDEVCAPS_PARMS {
  ULONG     ulLength;                                    /*  Input.  Length of the structure. */
  ULONG     ulMax_Caps;                                  /*  Output.  Returns maximum capabilities supported. */
  ULONG     ulNum_Caps;                                  /*  Output.  Returns number of capabilities returned. */
  ULONG     ulResv01;                                    /*  Reserved. */
  ULONG     ulResv02;                                    /*  Reserved. */
  ULONG     ulResv03;                                    /*  Reserved. */
  ULONG     ulResv04;                                    /*  Reserved. */
  ULONG     bSupports[DC_MAX_DEVCAP];  /*  Output.  Capability entries. */
} VSD_GETDEVCAPS_PARMS;

typedef   VSD _ GETDEVCAPS _ PARMS   * PVSD _ GETDEVCAPS _ PARMS ; </pre>




=== VSD_GETDEVCAPS_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Input. Length of the structure.





=== VSD_GETDEVCAPS_PARMS Field - ulMax_Caps ===

'''ulMax_Caps'''([[00998.htm|ULONG]]) Output. Returns maximum capabilities supported.





=== VSD_GETDEVCAPS_PARMS Field - ulNum_Caps ===

'''ulNum_Caps'''([[00998.htm|ULONG]]) Output. Returns number of capabilities returned.





=== VSD_GETDEVCAPS_PARMS Field - ulResv01 ===

'''ulResv01'''([[00998.htm|ULONG]]) Reserved.





=== VSD_GETDEVCAPS_PARMS Field - ulResv02 ===

'''ulResv02'''([[00998.htm|ULONG]]) Reserved.





=== VSD_GETDEVCAPS_PARMS Field - ulResv03 ===

'''ulResv03'''([[00998.htm|ULONG]]) Reserved.





=== VSD_GETDEVCAPS_PARMS Field - ulResv04 ===

'''ulResv04'''([[00998.htm|ULONG]]) Reserved.





=== VSD_GETDEVCAPS_PARMS Field - bSupports[DC_MAX_DEVCAP] ===

'''bSupports[DC_MAX_DEVCAP]'''([[00998.htm|ULONG]]) The following table lists the valid device capabilities.

<pre class="western">/---------------------------------------------------\
|Device Capabilities      |Supported Command        |
|-------------------------+-------------------------|
|DC_HASAUDIO              |All audio functions      |
|-------------------------+-------------------------|
|DC_HASVIDEO              |All video functions      |
|-------------------------+-------------------------|
|DC_HASVOLUME             |VSD_QUERYVOLUME          |
|                         |VSD_SETVOLUME            |
|-------------------------+-------------------------|
|DC_HASDISPLAY            |VSD_QUERYDISPLAY         |
|                         |VSD_SETDISPLAY           |
|-------------------------+-------------------------|
|DC_HASAUDIOATTRIBUTES    |VSD_QUERYAUDIOATTRIBUTES |
|                         |VSD_SETAUDIOATTRIBUTES   |
|-------------------------+-------------------------|
|DC_HASAUDIOCAPABILITIES  |VSD_QUERYDATATYPE        |
|                         |VSD_SETDATATYPE          |
|-------------------------+-------------------------|
|DC_HASVIDEOATTRIBUTES    |VSD_QUERYVIDEOATTRIBUTES |
|                         |VSD_SETVIDEOATTRIBUTES   |
|-------------------------+-------------------------|
|DC_HASIMAGEATTRIBUTES    |VSD_QUERYIMAGEATTRIBUTES |
|                         |VSD_SETIMAGEATTRIBUTES   |
|-------------------------+-------------------------|
|DC_HASESCAPE             |VSD_ESCAPE               |
|-------------------------+-------------------------|
|DC_HASINPUTLEVEL         |VSD_QUERYINPUTLEVEL      |
|                         |VSD_SETINPUTLEVEL        |
|-------------------------+-------------------------|
|DC_HASSTATUSLEVEL        |VSD_QUERYSTATUSLEVEL     |
|-------------------------+-------------------------|
|DC_HASMONITOR            |VSD_QUERYMONITOR         |
|                         |VSD_SETMONITOR           |
|-------------------------+-------------------------|
|DC_CANEJECT              |VSD_EJECT                |
|-------------------------+-------------------------|
|DC_CANLOAD               |VSD_LOAD                 |
|-------------------------+-------------------------|
|DC_HASDOOR               |VSD_QUERYDOOR            |
|                         |VSD_SETDOOR              |
|-------------------------+-------------------------|
|DC_HASTRACKS             |VSD_QUERYTRACKS          |
|                         |VSD_SETTRACKS            |
|-------------------------+-------------------------|
|DC_HASMEDIA              |VSD_QUERYMEDIATYPE       |
|-------------------------+-------------------------|
|DC_HASCOMSETTINGS        |VSD_QUERYCOMMSETTINGS    |
|                         |VSD_SETCOMSETTINGS       |
|-------------------------+-------------------------|
|DC_HASMEDIATYPE          |VSD_QUERYMEDIATYPE       |
|-------------------------+-------------------------|
|DC_HASKEYLOCK            |VSD_QUERYKEYLOCK         |
|                         |VSD_SETKEYLOCK           |
|-------------------------+-------------------------|
|DC_CANCUE                |VSD_QUERYCUE             |
|                         |VSD_SETCUE               |
|-------------------------+-------------------------|
|DC_HASCOUNTER            |VSD_QUERYCOUNTER         |
|                         |VSD_SETCOUNTER           |
|-------------------------+-------------------------|
|DC_CANRESET              |VSD_RESET                |
|-------------------------+-------------------------|
|DC_HASPOSITION           |VSD_QUERYPOSITION        |
|                         |VSD_SETPOSITION          |
|-------------------------+-------------------------|
|DC_HASLENGTH             |VSD_QUERYLENGTH          |
|                         |VSD_SETLENGTH            |
|-------------------------+-------------------------|
|DC_CANPARK               |VSD_PARK                 |
|-------------------------+-------------------------|
|DC_HASCONNECTOR          |VSD_QUERYCONNECTOR       |
|                         |VSD_SETCONNECTOR         |
|-------------------------+-------------------------|
|DC_HASEVENTS             |VSD_EVENT                |
|-------------------------+-------------------------|
|DC_HASDIRECTION          |VSD_QUERYDIRECTION       |
|                         |VSD_SETDIRECTION         |
|-------------------------+-------------------------|
|DC_HASVIEWPORT           |VSD_QUERYVIEWPORT        |
|                         |VSD_SETVIEWPORT          |
|-------------------------+-------------------------|
|DC_CANCAPTUREIMAGE       |VSD_CAPTUREIMAGE         |
|-------------------------+-------------------------|
|DC_CANRESTOREIMAGE       |VSD_RESTOREIMAGE         |
|-------------------------+-------------------------|
|DC_HASRAM                |Informational            |
|-------------------------+-------------------------|
|DC_AUDIOSETTINGS         |Informational            |
|-------------------------+-------------------------|
|DC_IMAGESETTINGS         |Informational            |
|-------------------------+-------------------------|
|DC_QUERYMINSEEKTIME      |Informational            |
|-------------------------+-------------------------|
|DC_QUERYTIME             |Informational            |
|-------------------------+-------------------------|
|DC_STEP                  |Informational            |
|-------------------------+-------------------------|
|DC_CAN_MIX               |Mixer functions are      |
|                         |available                |
|-------------------------+-------------------------|
|DC_HASCLOCK              |Informational            |
|-------------------------+-------------------------|
|DC_HASPOWER              |Informational            |
|-------------------------+-------------------------|
|DC_HASZOOM               |Informational            |
|-------------------------+-------------------------|
|DC_HASFOCUS              |Informational            |
|-------------------------+-------------------------|
|DC_HASCHANNELS           |Informational            |
|-------------------------+-------------------------|
|DC_CANSTREAM             |VSD_DDCMD                |
|-------------------------+-------------------------|
|DC_CANSCALE              |Informational            |
|-------------------------+-------------------------|
|DC_CANDISTORT            |Informational            |
|-------------------------+-------------------------|
|DC_CANSTRETCH            |Informational            |
|-------------------------+-------------------------|
|DC_HASTUNER              |Informational            |
|-------------------------+-------------------------|
|DC_HASTELETEX            |Informational            |
\---------------------------------------------------/</pre>
'''Note:'''''Informational''in the above table indicates the device has the capability, but does not indicate that a particular command is supported.





=== VSD_OPEN_PARMS ===

This structure contains fields for the [[00290.htm|VSD_OPEN]]message.

<pre class="western">typedef struct _VSD_OPEN_PARMS {
  ULONG     ulLength;                                          /*  Input.  Length of the structure. */
  ULONG     ulCategory;                                        /*  Name of unit to open. */
  CHAR      szInstallName[MAX_DEVICE_NAME];  /*  Installation name of MCD. */
  CHAR      szPDDName[MAX_DEVICE_NAME];      /*  Name of PDD to open. */
  HVSD      hvsd;                                              /*  Output.  Handle to the VSD driver. */
  PFN       pfEvent;                                           /*  Output.  (Unused) */
  PVOID     pDevInfo;                                          /*  Device-specific info. */
  ULONG     ulDDStream;                                        /*  Input.  Device driver stream identifier. (Unused) */
} VSD_OPEN_PARMS;

typedef   VSD _ OPEN _ PARMS   * PVSD _ OPEN _ PARMS ; </pre>




=== VSD_OPEN_PARMS Field - ulLength ===

'''ulLength'''([[00998.htm|ULONG]]) Input. Length of the structure.





=== VSD_OPEN_PARMS Field - ulCategory ===

'''ulCategory'''([[00998.htm|ULONG]]) Input. Name of unit to open. (Currently unused)





=== VSD_OPEN_PARMS Field - szInstallName[MAX_DEVICE_NAME] ===

'''szInstallName[MAX_DEVICE_NAME]'''([[00753.htm|CHAR]]) Input. Installation name of the MCD. This field contains information that can be optionally ignored. (Unused)





=== VSD_OPEN_PARMS Field - szPDDName[MAX_DEVICE_NAME] ===

'''szPDDName[MAX_DEVICE_NAME]'''([[00753.htm|CHAR]]) Input. Name of PDD to open. This field contains information that can be optionally ignored.





=== VSD_OPEN_PARMS Field - hvsd ===

'''hvsd'''([[00810.htm|HVSD]]) Output. Handle to the VSD driver.





=== VSD_OPEN_PARMS Field - pfEvent ===

'''pfEvent'''([[00952.htm|PFN]]) Output. (Unused)





=== VSD_OPEN_PARMS Field - pDevInfo ===
'''pDevInfo'''([[01203.htm|PVOID]]) Input/Output. Device-specific or media-specific information. For audio, it points to [[01138.htm|VSD_AUDIOOPEN_PARMS]]

=== VSD_OPEN_PARMS Field - ulDDStream ===
'''ulDDStream'''([[00998.htm|ULONG]]) Input. Device driver stream identifier. (Unused)

=== VSD_RESOURCE_PARMS ===
This structure contains fields for the [[00394.htm|VSD_RESOURCE]]command.

<pre class="western">typedef struct _VSD_RESOURCE_PARMS {
  ULONG     ulLength;                    /*  Length of the structure. */
  CHAR      szPDDName[MAX_DEVICE_NAME];  /*  Input.  Device driver name. */
  ULONG     ulDevType;                   /*  Input.  Device type to open. */
  ULONG     ulDataType;                  /*  Input.  Data type to open. */
  ULONG     ulResUnits;                  /*  Output.  Resource units. */
  ULONG     ulClass;                     /*  Output.  Resource class. */
} VSD_RESOURCE_PARMS;

typedef   VSD _ RESOURCE _ PARMS   * PVSD _ RESOURCE _ PARMS ; </pre>

=== VSD_RESOURCE_PARMS Field - ulLength ===
'''ulLength'''([[00998.htm|ULONG]]) Length of the structure.

=== VSD_RESOURCE_PARMS Field - szPDDName[MAX_DEVICE_NAME] ===
'''szPDDName[MAX_DEVICE_NAME]'''([[00753.htm|CHAR]]) Input. Name of device driver to open.

=== VSD_RESOURCE_PARMS Field - ulDevType ===
'''ulDevType'''([[00998.htm|ULONG]]) Input. Device type to open.

=== VSD_RESOURCE_PARMS Field - ulDataType ===
'''ulDataType'''([[00998.htm|ULONG]]) Input. Data type to open.

=== VSD_RESOURCE_PARMS Field - ulResUnits ===
'''ulResUnits'''([[00998.htm|ULONG]]) Output. Resource units consumed for requested mode.

=== VSD_RESOURCE_PARMS Field - ulClass ===
'''ulClass'''([[00998.htm|ULONG]]) Output. Resource class for requested mode (where mode is PCM, MIDI, etc.).

=== VSD_VOLUME_PARMS ===
This structure contains fields for the [[00384.htm|VSD_QUERYVOLUME]]and the [[00487.htm|VSD_ SETVOLUME]]commands.

<pre class="western">typedef struct _VSD_VOLUME_PARMS {
  ULONG     ulLength;       /*  Length of structure. */
  ULONG     ulFlags;        /*  Volume item to operate on. */
  ULONG     ulRequest;      /*  Unused. */
  ULONG     ulVectoredVol;  /*  Input.  Time for volume change to take place. */
  ULONG     ulMasterAudio;  /*  Input.  Master audio setting. */
  ULONG     ulVolume;       /*  Input/Output.  Volume for connector. */
  ULONG     hConn;          /*  Handle to connector.  (Unused) */
  BOOL      fMute;          /*  Input/Output.  Muted or not muted. */
} VSD_VOLUME_PARMS;

typedef   VSD _ VOLUME _ PARMS   * PVSD _ VOLUME _ PARMS ; </pre>

=== VSD_VOLUME_PARMS Field - ulLength ===
'''ulLength'''([[00998.htm|ULONG]]) Length of structure.

=== VSD_VOLUME_PARMS Field - ulFlags ===
'''ulFlags'''([[00998.htm|ULONG]]) Input. Volume item to operate on.

The following flags (subcommands) are defined for this command:

VSD_VOLUME Instance volume.

VSD_MASTERVOLUME System-wide volume setting.

VSD_MUTE Flag indicating mute setting.

=== VSD_VOLUME_PARMS Field - ulRequest ===
'''ulRequest'''([[00998.htm|ULONG]]) Unused.

=== VSD_VOLUME_PARMS Field - ulVectoredVol ===
'''ulVectoredVol'''([[00998.htm|ULONG]]) Input. Time for volume change to take place.

=== VSD_VOLUME_PARMS Field - ulMasterAudio ===
'''ulMasterAudio'''([[00998.htm|ULONG]]) Input. Master audio setting.

=== VSD_VOLUME_PARMS Field - ulVolume ===
'''ulVolume'''([[00998.htm|ULONG]]) Input/Output. Volume for connector.

=== VSD_VOLUME_PARMS Field - hConn ===
'''hConn'''([[00998.htm|ULONG]]) Handle to connector to operate on. (Unused)

=== VSD_VOLUME_PARMS Field - fMute ===
'''fMute'''([[00751.htm|BOOL]]) Input/Output. Indicates if volume should be muted.

=== VOID ===
A data area of undefined format.
<pre class="western">#define VOID void</pre>

=== Types of MIDI Messages ===
There are three types of MIDI system messages:

�System common <br />�System exclusive <br />�System real time

''System-common''messages are intended for all receivers, regardless of channel. ''System-exclusive''messages are defined by the manufacturer and are not limited in length. ''System-real-time''messages can interrupt other messages because they carry timing information. For example, a long system message might have an embedded timer message within it. Other MIDI events cannot occur within a system message or nested system message; however, a system message can occur in the middle of other MIDI events.

While in MIDI mode, almost all functions provided by audio device drivers can be controlled by the application by using system-exclusive messages.

=== General Format of System-Exclusive Messages ===
The general format of system-exclusive messages is shown in the following table:

<pre class="western">/-------------------------------------------------------------\
|Message Description          |Hexadecimal Format             |
|-----------------------------+-------------------------------|
|Timing compression (long)    |F0  00 00 3A  01  lsb  msb  F7 |
|-----------------------------+-------------------------------|
|Timing compression (short)   |F0  00 00 3A  07-7F  F7        |
|-----------------------------+-------------------------------|
|Sound generator commands     |F0  00 00 3A  02  unit  cmd    |
|                             |chan ...  F7                   |
|-----------------------------+-------------------------------|
|Device driver control        |F0  00 00 3A  03  cmd  ...  F7 |
|-----------------------------+-------------------------------|
|Device driver query          |F0  00 00 3A  04  qid  F7      |
|-----------------------------+-------------------------------|
|Device driver response       |F0  00 00 3A  05  qid  data F7 |
|-----------------------------+-------------------------------|
|Timbre parameter             |F0  00 00 3A  06  cmd  hh mm ll|
|                             |... F7                         |
\-------------------------------------------------------------/</pre>
The following list contains the categories of system exclusive messages:

�[[01206.htm|Device Driver Control Messages]]<br />�[[01207.htm|Device Driver Query Messages]]<br />�[[01208.htm|Device Driver Response Messages]]<br />�[[01209.htm|Sound Generator Commands Messages]]<br />�[[01210.htm|Timbre Parameter Messages]]<br />�[[01211.htm|Timing Compression Messages]]

=== Device Driver Control Messages ===
The following are types of device driver control messages:

�Balance <br />�Generic sound selection <br />�Master volume <br />�Tempo <br />�Timing generation <br />�Volume

'''Balance Control'''

This message sets the balance level for the audio device driver:

<pre class="western">  F0  00 00 3A  03  08  bl  dl  dm  F7

  bb = Balance level (0 = full left, 40 = middle, 7F = full right)
  dl = Duration LSB
  dm = Duration MSB</pre>
''Balance''is specified as a relative value from 0 - 7F, where ''0''is full left, ''40''is middle, ''7F''is full right. The duration specifies the length of time (in tenths of a second) necessary to gradually go from the current level to the target level. For example, to set the balance to full right (7F) with duration set to ''10''to gradually move the new balance to the right over a one-second period, the balance control message would be:

<pre class="western">  F0  00 00 3A  03 08 7F 0A 00 F7</pre>
'''Generic Sound Selection'''

This message selects the generic sound for an instrument:

<pre class="western">  F0  00 00 3A  03  03  ii  tt  ss  F7

  ii = Instrument number
  tt = Sound type (0 = Musical instrument, 1 = sound effects)
  ss = Sound ID</pre>
There are 128 generic musical instrument sounds and 128 sound effects types . When a requested sound is not available on a device, the nearest available sound is used. It is recommended that general MIDI mode be used instead of this message.

'''Master Volume Control'''

This message sets the master volume level for the audio device driver:

<pre class="western">  F0  00 00 3A  03  09  vl  vm  00  F7

  vl = Master Volume LSB
  vm = Master Volume MSB</pre>
Master volume is intended to permit immediate control of overall volume without interfering with the current volume setting as set by the volume control message, described in '''Volume Control'''below. ''Volume''is specified as a relative value from 0 - 3FFF. For example, to set the volume to maximum ( 3FFF) the master volume control message would be:

<pre class="western">  F0  00 00 03 03 09 7F 7F 00 F7</pre>
This message causes a MIDI volume control change message to be generated. Any subsequent volume control change messages encountered are scaled proportionately. Actual volume is the product of volume and master volume.

'''Tempo Control'''

This message sets the tempo for system real-time timing clock generation:

<pre class="western">  F0  00 00 3A 03  02  tl  tm  dd  F7

  tl = Tempo LSB
  tm = Tempo MSB
  dd = Duration</pre>
Notice that ''tempo''is expressed as 1/10 beats per minute. The duration specifies the length of time (in tenths of a second) necessary to go gradually from the current tempo to the specified tempo. For example, to set the tempo to 120 beats per minute, with duration set to ''0''to make the new tempo effective immediately, the tempo control message would be:

<pre class="western">  120 bpm = 1200 1/10 increments
            1200 decimal = 00000100 10110000 binary
            7 bit MSB (tm) = 000100 1        = hex 9
            7 bit LSB (tl) =         0110000 = hex 30

   F0 00 00 3A 03 02 30 09 00 F7</pre>
'''Timing Generation Control'''

This message tells the device driver what timing information to generate:

<pre class="western">  F0  00 00 3A  03  01  tt  pp  00  F7

  tt = System real-time control flags (default 08H)
       0x1x xxxx  Output timing clocks to MIDI-Out
       0x0x xxxx  Do not output timing clocks to MIDI-Out (default)
       0xx1 xxxx  Merge timing clocks with MIDI-In
       0xx0 xxxx  Do not pass timing clocks to MIDI-In (default)
       0xxx 1xxx  Synchronize output to timing clocks (default)
       0xxx 0xxx  Disable output synchronization
       0xxx x1xx  Perform timing data compression
       0xxx x0xx  Disable timing data compression (default)
       0xxx xxRR  Reserved bits - always 0

  pp = System real-time 24 CPQN rate prescaler
       00dd dddd  Multiply by dddddd+1 (1-64) for 24 to 1536 ppq
       01dd dddd  Divide by dddddd+1*3   ( 3 - 192 )   for   8   to   1 / 8   ppq </pre>
By default, device drivers utilize real-time messages at a rate of 24 per quarter note (beat) and 120 beats per minute internally for performing output synchronization. However, they do not queue timing clocks to either MIDI-Out or MIDI-In (Read data).

'''Volume Control'''

This message sets the volume level for the audio device driver. Volume is specified as a relative value from 0-7F.

<pre class="western">  F0  00 00 3A  03  07  vv  dl  dm  F7

  vv = Volume (0-7F)
  dl = Duration LSB
  dm = Duration MSB</pre>
The duration specifies the length of time (in tenths of a second) necessary to gradually go from the current level to the target level. For example, to set the volume to maximum (7F) with duration set to ''0''to make the new volume effective immediately, the volume control message would be:

<pre class="western">  F0  00 00 3A 03 07 7F 00 00 F7</pre>
This message causes subsequent MIDI volume control change messages to be generated. Any subsequent volume control change message encountered will be scaled proportionately. Notice that the actual volume is the product of volume and master volume.

=== Device Driver Query Messages ===

The following are types of device driver query messages:
*Query device capability
*Query Device ID
*Query output queue size

'''Query Device Capability'''

This message is issued to a device driver by an application to query the basic capability of a device driver:

<pre class="western">  F0 00 00 3A  04  01  F7</pre>
The device driver responds to this message by returning a device capability response message (see [[01208.htm|Device Driver Response Messages]]).

'''Query Device ID'''

This message is issued to a device driver by an application to request the identity of the device driver:

<pre class="western">  F0 00 00 3A  04  04  F7</pre>
The device driver responds to this message by returning a device ID response message, which identifies the device (see [[01208.htm|Device Driver Response Messages]]).

'''Query Output Queue Size'''

This message is issued to a device driver by an application to request the size of the output queue:

<pre class="western">  F0 00 00 3A  04  02  F7</pre>
The device driver responds to this message by returning a queue size response message (see [[01208.htm|Device Driver Response Messages]])

=== Device Driver Response Messages ===
The following are types of device driver response messages:
* Device capability
* Device ID
* Queue size

'''Device Capability Response'''

This message is sent by a device driver in response to a query device capability message (see [[01207.htm|Device Driver Query Messages]]). It indicates the basic MIDI capability of the device driver.

<pre class="western">  F0 00 00 3A  05  01  ii mm 00 F7

  ii = Number of sound generators (instruments)
  mm = MIDI capability flags
       01xx xxxx MIDI input is supported
       0x1x xxxx MIDI output is supported
       0xx1 xxxx System real-time Timing clocks are supported</pre>
'''Device ID Response'''

This message identifies the device and is sent by a device driver in response to a query device ID message (see [[01207.htm|Device Driver Query Messages]]).

<pre class="western">  F0 00 00 3A  05  04  b1 b2 b3 F7

  b1 = 1st byte of Device ID
  b2 = 2nd byte of Device ID
  b3 = 3rd byte of Device ID</pre>
This message is provided to permit applications to perform device unique operations such as issuing device-specific system exclusive messages.

'''Queue Size Response'''

This message is sent by a device driver in response to a query output queue size message (see [[01207.htm|Device Driver Query Messages]]). It indicates the total output queue size in bytes.

<pre class="western">  F0 00 00 3A  05  02  ll mm 00 F7

  ll = Lower 7 bits of queue size
  mm = Upper 7 bits of queue size
  (Queue Size in bytes = 00mm mmmm mlll llll)</pre>
For example, if the device driver's output queue is 512 bytes in length, the returned data is:

<pre class="western">   F0 00 00 3A  05  02  00  04  00  F7</pre>

=== Sound Generator Commands Messages ===
These messages are specific to a certain device. Although not part of the audio device driver's architecture, they are included here. Notice in the following example that the 6th MIDI byte identifies the specific IBM device that is addressed:

<pre class="western">   M-ACPA (IBM Audio Capture &amp; Playback Adapter)</pre>
'''Program Change Enable'''

This message instructs the M-ACPA synthesizer to honor or ignore MIDI program change messages (Cn).

<pre class="western">  F0  00 00 3A  02  01  01  ee  00  F7

  ee = Program Changes Enable (0 = disabled, 1 = enabled; default)</pre>
By default, program changes are honored. Notice that this message does not affect generic sound selection messages, which are always honored.

=== Timbre Parameter Messages ===
Timbre parameter messages are provided to permit interrogating and changing of the parameters that control the timbre of a given voice. Parameters are addressed using three 7-bit bytes (that is, 21 bits), enabling approximately two million parameters to be addressed. In most cases, these parameters are divided into units such as banks, voices, and so forth. Parameter values are passed in two 7-bit bytes, allowing up to 14-bits per parameter.

The following are types of timbre parameter messages:
* Query timbre parameter
* Request timbre block
* Set timbre parameter
* Timbre block
* Timbre parameter response
* Write timbre block

'''Query Timbre Parameter'''

This message is issued to a device driver by an application to request the current setting of a timbre parameter:

<pre class="western">  F0 00 00 3A  06  01  hh  mm  ll  F7

  hh = High 7-bits parameter #
  mm = Middle 7-bits parameter #
  ll = Low 7-bits parameter #</pre>
The device driver responds to this message by returning a timbre parameter response message (see below).

'''Request Timbre Block'''

This message is issued to a device driver by an application to request a block of timbre data.

<pre class="western">  F0 00 00 3A  06  04  hh  mm  00  F7

  hh = High 7-bits block #
  mm = Middle 7-bits block #</pre>
The device driver responds to this message by returning a timbre block message (see below).

'''Set Timbre Parameter'''

This message is used to set or change a timbre parameter:

<pre class="western">  F0 00 00 3A  06  03  hh mm ll dl dm F7

  hh = High 7-bits parameter #
  mm = Middle 7-bits parameter #
  ll = Low 7-bits parameter #
  dl = Parameter data LSB (0-127)
  dm = Parameter data MSB</pre>
'''Timbre Block'''

This message is issued by a device driver in response to a request timber block message (see above). It transfers blocks of timbre data from a device driver to an application.

<pre class="western">  F0 00 00 3A  06  05  hh  mm  ll  &lt; len &gt;  F7

  hh = High 7-bits block #
  mm = Middle 7-bits block #
  ll = Length of 7-bit data
  &lt; len &gt; = Variable length (7-bit) data block</pre>
'''Timbre Parameter Response'''

This message is sent by a device driver in response to a query timbre parameter message (see above). It returns the current value of a timbre parameter.

<pre class="western">  F0 00 00 3A  06  02  hh mm ll dl dm F7

  hh = High 7-bits parameter #
  mm = Middle 7-bits parameter #
  ll = Low 7-bits parameter #
  dl = Parameter data LSB (0-127)
  dm = Parameter data MSB</pre>
'''Write Timbre Block'''

This message is issued to a device driver by an application to write a block of timbre data:

<pre class="western">  F0 00 00 3A  06  06  hh  mm  ll  &lt; len &gt;  F7

  hh = High 7-bits block #
  mm = Middle 7-bits block #
  ll = Length of 7-bit data
  &lt; len &gt; = Variable length (7-bit) data block</pre>

=== Timing Compression Messages ===
These messages are used to compress sequential timing clocks (F8) into a single system exclusive message. Up to 16383 (that is, F8 Timing clocks can be compressed into a single 6- or 8-byte message, which can be written to a device driver to cause a delay between output events if output synchronizing is enabled (see ''Device Driver Control Messages'').

<pre class="western"> F0  00 00 3A  01  ll  mm  F7  (Long version)
 F0  00 00 3A  nn  F7          (Short version)

 ll = Number of System Real Time Timing Clocks LSB
 mm = Number of System Real Time Timing Clocks MSB
 nn = Number of System Real Time Timing Clocks (nn = 7 through 127)</pre>
The short version can be used to represent durations of from 7 - 127 clocks . Longer durations can be represented with the long version, where the number of timing clocks that have occurred is calculated by combining the low 7-bits of ''mm'' with the low 7-bits of ''ll'' to produce a single 16-bit value:

 0mmm mmmm + 0lll llll = 00mm mmmm mlll llll

=== OS/2 Version Compatibility Considerations ===
The following table lists items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.

 /--------------------------------------------------------------\
 |Item Added or       |Date Item Added or  |Compatibility of    |
 |Changed             |Changed             |Addition or Change  |
 |--------------------+--------------------+--------------------|
 |MIDI Driver         |November 1995       |OS/2 Warp, Version  |
 |                    |                    |3.0 and Later       |
 |--------------------+--------------------+--------------------|
 |Timer Device Driver |November 1995       |OS/2 Warp, Version  |
 |                    |                    |3.0 and Later       |
 |--------------------+--------------------+--------------------|
 |VSD Updates         |November 1995       |OS/2 Warp, Version  |
 |                    |                    |3.0 and Later       |
 \--------------------------------------------------------------/

=Notices=

'''IBM Developer Connection Device Driver Kit for OS/2, Version 4.02 Edition ( September 1997)'''

'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:'''INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

=== Copyright Notices ===

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: &quot;(C) (your company name) (year). All rights reserved.&quot;

'''(C) Copyright International Business Machines Corporation 1996. All rights reserved.'''<br />Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.





=== Disclaimers ===

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing <br />IBM Corporation <br />500 Columbus Avenue <br />Thornwood, NY 10594 <br />U.S.A.





=== Trademarks ===

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

<pre class="western">IBM
Multimedia Presentation Manager/2
OS/2
Ultimotion </pre>
The following terms are trademarks of other companies:

Helvetica Linotype Company <br />MASM Microsoft Corporation <br />Mitsumi Mitsumi Denki Kabushki Kaisha <br />Panasonic Matsushita Electric Industrial Co., Ltd. <br />OPTi OPTi, Inc. <br />Pioneer Pioneer Electric Corporation <br />ProAudio Spectrum Media Vision, Inc. <br />ProAudio Spectrum 16 Media Vision, Inc. <br />QuickVia Jovian Logic Corp. <br />ReelMagic Sigma Designs, Inc. <br />Sound Blaster Creative Technology Ltd. <br />SuperVia Jovian Logic Corp. <br />Super VideoWindows New Media Graphics Corporation <br />Video Blaster Creative Technology, Inc. <br />Yamaha Yamaha Corporation

Windows is a trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.






'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''

[[Category:Driver Articles]]
[[Category:MMOS/2]]
[[Category:Multimedia]]
[[Category:MIDI]]