Jump to content

MMPM/2 Device Driver Reference:Vendor-Specific Driver Commands: Difference between revisions

From EDM2
Created page with "=== Vendor-Specific Driver Commands === The vendor-specific driver (VSD) commands enable communication between vendor-specific drivers (VSDs) and an application such as the u..."
 
No edit summary
Line 1: Line 1:
=== Vendor-Specific Driver Commands ===
==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 ''VSDEntry'' entry point.
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>
 
-----


==VSDEntry==
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.
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>
<pre class="western">#define INCL_AUDIO_VSD
#define INCL_AUDIO_VSD
#include &lt;vsdcmds.h&gt;
#include <vsdcmds.h>
#include &lt;os2mixer.h&gt;
#include <os2mixer.h>


HVSD    hvsd;      /*  Handle to VSD instance. */
HVSD    hvsd;      /*  Handle to VSD instance. */
Line 34: Line 15:
ULONG    rc;        /*  Return codes. */
ULONG    rc;        /*  Return codes. */


rc = VSDEntry(hvsd, ulFunc, ulFlags, pRequest);</pre>
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 ===
=== VSDEntry Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) - input This parameter is the handle to the VSD instance.


'''hvsd'''([[00810.htm|HVSD]]) - input This parameter is the handle to the VSD instance.
=== VSDEntry Parameter - ulFunc ===
 
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) - input The VSD command to be issued. The following commands are supported for audio VSDs.
 
<pre>
 
/-------------------------------------------------------------\
 
 
=== 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                  |
|Command                      |Description                  |
|------------------------------+------------------------------|
|------------------------------+------------------------------|
Line 105: Line 60:
|                              |to be passed into the VSD.    |
|                              |to be passed into the VSD.    |
|                              |(Optional)                    |
|                              |(Optional)                    |
\-------------------------------------------------------------/</pre>
\-------------------------------------------------------------/
</pre>


=== VSDEntry Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|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''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 Parameter - ulFlags ===
=== VSDEntry - Remarks ===
If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.


'''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.
==VSD_CLOSE==
This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_CLOSE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to the VSD to be closed.


=== VSD_CLOSE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_CLOSE.


=== VSDEntry Parameter - pRequest ===
=== VSD_CLOSE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


'''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.
=== VSD_CLOSE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|PVOID]]) Not used for this command.


=== VSD_CLOSE Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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>
HVSD    hvsd;
    ULONG    rc;


    rc = pInstance ->pfnAUDIOIF(  hvsd,
                                  VSD_CLOSE,
                                  0,
                                  0 );
    return (rc);
</pre>


=== VSDEntry Return Value - rc ===
==VSD_DDCMD==
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 [[#VSDEntry|VSDEntry]] as follows:
 
  VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
 
=== VSD_DDCMD Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.
 
=== VSD_DDCMD Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_DDCMD.
 
=== VSD_DDCMD Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 [[MMPM/2 Device Driver Reference:Data Types#DDCMDCONTROL|DDCMDCONTROL]] structure.


'''rc'''([[00998.htm|ULONG]]) - returns The return codes are listed for each command and will vary based on the command sent.
DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. ''pRequest'' is a pointer to [[MMPM/2 Device Driver Reference:Data Types#DDCMDDEREGISTER|DDCMDDEREGISTER]] structure.


If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.
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 [[MMPM/2 Device Driver Reference:Data Types#MSG_REPORTINT|MSG_REPORTINT]] structure to the ''pSHDEntryPoint'' in [[MMPM/2 Device Driver Reference:Data Types#DDCMDREGISTER|DDCMDREGISTER]] to inform the caller.


''pRequest'' is a pointer to [[MMPM/2 Device Driver Reference:Data Types#DDCMDREADWRITE|DDCMDREADWRITE]] structure.


DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. ''pRequest'' is a pointer to [[MMPM/2 Device Driver Reference:Data Types#DDCMDREGISTER|DDCMDREGISTER]] structure.


DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest'' is a pointer to [[MMPM/2 Device Driver Reference:Data Types#DDCMDSETUP|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 [[MMPM/2 Device Driver Reference:Data Types#DDCMDSTATUS|DDCMDSTATUS]] structure.


=== VSDEntry - Parameters ===
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 [[MMPM/2 Device Driver Reference:Data Types#MSG_REPORTINT|MSG_REPORTINT]] structure to the ''pSHDEntryPoint'' in [[MMPM/2 Device Driver Reference:Data Types#DDCMDREGISTER|DDCMDREGISTER]] to inform the caller.


'''hvsd'''([[00810.htm|HVSD]]) - input This parameter is the handle to the VSD instance.
''pRequest'' is a pointer to [[MMPM/2 Device Driver Reference:Data Types#DDCMDREADWRITE|DDCMDREADWRITE]] structure.


'''ulFunc'''([[00998.htm|ULONG]]) - input The VSD command to be issued. The following commands are supported for audio VSDs.
=== VSD_DDCMD Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|PVOID]]) The value of ''pRequest'' varies according to the ''ulFlags'' value. See each particular ''ulFlags'' value for the definition of ''pRequest''.


<pre class="western">/-------------------------------------------------------------\
=== VSD_DDCMD Return Value - rc ===
|Command                      |Description                  |
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.
|------------------------------+------------------------------|
 
|VSD_CLOSE                    |Closes the device. (Required) |
=== VSD_DDCMD - Remarks ===
|------------------------------+------------------------------|
A user-level 32-bit buffer pointer is available in the ''pProcessLin'' field of the [[MMPM/2 Device Driver Reference:Data Types#DDCMDREADWRITE|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 [[MMPM/2 Device Driver Reference:Data Types#DDCMDREADWRITE|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                    |Allows communication between  |
 
|                              |stream handlers and their    |
==VSD_GETDEVCAPS==
|                              |attached devices. (Required) |
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.
|------------------------------+------------------------------|
|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>


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


'''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(hvsd, ulFunc, ulFlags, 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.
=== VSD_GETDEVCAPS Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


'''rc'''([[00998.htm|ULONG]]) - returns The return codes are listed for each command and will vary based on the command sent.
=== VSD_GETDEVCAPS Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_GETDEVCAPS.


If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.
=== VSD_GETDEVCAPS Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


=== VSD_GETDEVCAPS Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_GETDEVCAPS_PARMS|PVSD_GETDEVCAPS_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_GETDEVCAPS_PARMS|VSD_GETDEVCAPS_PARMS]] data structure.


=== VSD_GETDEVCAPS Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 [[MMPM/2 Device Driver Reference:Data Types#VSD_GETDEVCAPS_PARMS|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.


=== VSDEntry - Remarks ===
=== VSD_GETDEVCAPS - Example Code ===
The following code illustrates how to determine device capabilities for a VSD.
<pre>
  HVSD                  hvsd;
  VSD_GETDEVCAPS_PARMS  vsdDevCaps;


If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.
  rc = pInstance->pfnAUDIOIF(  hvsd,
                              VSD_GETDEVCAPS
                              0,
                              (PVOID) &vsdDevCaps );


  if (!rc)
    {
    /* If the VSD doesn't support volume  */


    if( !vsdDevCaps.bSupports[ DC_HASVOLUME] )
      {
      return ( rc );
      }
</pre>


==VSD_ESCAPE==
This optional command sends a buffer to the driver.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


=== VSDEntry - Topics ===
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


Select an item:
=== VSD_ESCAPE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


<pre class="western">Syntax
=== VSD_ESCAPE Parameter - ulFunc ===
Parameters
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_ESCAPE.
Returns
Remarks
Glossary </pre>


=== VSD_ESCAPE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


=== VSD_ESCAPE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_ESCAPE_PARMS|PVSD_ESCAPE_PARMS]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_ESCAPE_PARMS|VSD_ESCAPE_PARMS]] structure.


=== VSD_ESCAPE Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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_CLOSE ===
==VSD_INSERTSETTINGSPAGE==
This command enables a VSD to insert device-specific settings pages into the system configuration application.


=== VSD_INSERTSETTINGSPAGE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD instance.


-----
=== VSD_INSERTSETTINGSPAGE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_INSERTSETTINGSPAGE.


Select an item:
=== VSD_INSERTSETTINGSPAGE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


<pre class="western">Syntax
=== VSD_INSERTSETTINGSPAGE Parameter - pRequest ===
Returns
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#MCI_DEVICESETTINGS_PARMS|PMCI_DEVICESETTINGS_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#MCI_DEVICESETTINGS_PARMS|MCI_DEVICESETTINGS_ PARMS]] data structure.
Remarks
Example Code
Glossary </pre>


-----
=== VSD_INSERTSETTINGSPAGE Return Value - hwndRC ===
'''hwndRC''' ([[MMPM/2 Device Driver Reference:Data Types#HWND|HWND]]) The return code contains the handle to a settings page or zero if no page is inserted.


This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.
=== VSD_OPEN ===
This command opens the device driver and returns a VSD handle or ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]). It should not allocate resources on the device (resource usage should be performed on the VSD restore).


This command is sent using [[00235.htm|VSDEntry]]as follows:
VSD_OPEN is a required command and must be implemented by all VSD writers.


<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


'''hvsd'''([[00810.htm|HVSD]]) Handle to the VSD to be closed.
=== VSD_OPEN Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Not used.


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_CLOSE.
=== VSD_OPEN Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_OPEN.


'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.
=== VSD_OPEN Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


'''pRequest'''([[01203.htm|PVOID]]) Not used for this command.
=== VSD_OPEN Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_OPEN_PARMS|PVSD_OPEN_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_OPEN_PARMS|VSD_OPEN_PARMS]] data structure.


'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:
=== VSD_OPEN Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


VSDERR_SUCCESS The command was successful.
=== 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.


VSDERR_CANNOT_CLOSE VSD is unable to close the device.
For an audio VSD, the ''pDevInfo'' pointer points to a [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIOOPEN_PARMS|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 [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIOOPEN_PARMS|VSD_AUDIOOPEN_PARMS]] structure with a valid data subtype.


VSDERR_HARDWARE A hardware error occurred.
=== VSD_OPEN - Example Code ===
The following code illustrates how to open an audio VSD.
<pre>
VSD_OPEN_PARMS        vsdOpenParms;
VSD_AUDIOOPEN_PARMS  vsdData;


vsdData.ulLength = sizeof(VSD_AUDIOOPEN_PARMS);
vsdData.ulFlags = 0;
vsdData.ulSamplingRate      = pInstance->lSRate;
vsdData.ulBitsPerSample      = pInstance->lBitsPerSRate;
vsdData.ulChannels          = pInstance->sChannels;
vsdData.ulDataType          = pInstance->sMode;
vsdData.ulDeviceID          = pInstance->ulDeviceID;
vsdData.ulOperation          = pInstance->ulOperation;
vsdOpenParms.pDevInfo = (PVOID)&vsdData;




    vsdOpenParms.ulLength = sizeof(VSD_OPEN_PARMS);
    memmove(&vsdOpenParms.szPDDName,
            pInstance->szDeviceName,
            strlen(pInstance->szDeviceName));
      /* Open the audio VSD */
    rc = pInstance->pfnAUDIOIF(0,
                                VSD_OPEN,
                                0L
                                (PVOID)&vsdOpenParms);
    if (!rc)
        }
        pInstance->hvsd = vsdOpenParms.hvsd;
        {
</pre>


==VSD_QUERY==
This command allows an application to query the status of the VSD.


=== VSD_CLOSE Parameter - hvsd ===
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


'''hvsd'''([[00810.htm|HVSD]]) Handle to the VSD to be closed.
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_QUERY Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_QUERY Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERY.


=== VSD_QUERY Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) The following flags can be used with VSD_QUERY:
*VSD_QUERYAUDIOATTRIBUTES See [[#VSD_QUERYAUDIOATTRIBUTES|VSD_QUERYAUDIOATTRIBUTES]].
*VSD_QUERYCONNECTOR See [[#VSD_QUERYCONNECTOR|VSD_QUERYCONNECTOR]].
*VSD_QUERYDATATYPE See [[#VSD_QUERYDATATYPE|VSD_QUERYDATATYPE]].
*VSD_QUERYMONITOR See [[#VSD_QUERYMONITOR|VSD_QUERYMONITOR]].
*VSD_QUERYVOLUME See [[#VSD_QUERYVOLUME|VSD_QUERYVOLUME]].
*VSD_QUERYMIXCONNECTIONS See [[#VSD_QUERYMIXCONNECTIONS|VSD_QUERYMIXCONNECTIONS]].
*VSD_QUERYMIXCONTROL See [[#VSD_QUERYMIXCONTROL|VSD_QUERYMIXCONTROL]].
*VSD_QUERYMIXLINE See [[#VSD_QUERYMIXLINE|VSD_QUERYMIXLINE]].


=== VSD_QUERY Return Value - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|PVOID]]) Pointer varies according to ''ulFlags''.


=== VSD_CLOSE Parameter - ulFunc ===
=== VSD_QUERY Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Error code indicating success or the type of failure:
*VSDERR_SUCCESS
:Command completed successfully.
*VSDERR_MISSING_PARAMETER
:One or more parameters are missing.


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_CLOSE.
=== VSD_QUERY - Remarks ===
This command uses flags to indicate what information is queried.


==VSD_QUERYAUDIOATTRIBUTES==
This subcommand of the [[#VSD_QUERY|VSD_QUERY]] command queries the current audio settings and capabilities. A valid length must be placed in the ''ulLength'' field of the [[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|VSD_AUDIOATTRIBUTES_PARMS]] structure and the audio setting (such as treble, bass, and so on) must be placed in the ''ulFlags'' field of the [[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|VSD_ AUDIOATTRIBUTES_PARMS]] structure.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_QUERYAUDIOATTRIBUTES Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_CLOSE Parameter - ulFlags ===
=== VSD_QUERYAUDIOATTRIBUTES Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.
=== VSD_QUERYAUDIOATTRIBUTES Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYAUDIOATTRIBUTES.


=== VSD_QUERYAUDIOATTRIBUTES Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|VSD_AUDIOATTRIBUTES_ PARMS]] structure.


=== VSD_QUERYAUDIOATTRIBUTES Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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>
HVSD                        hvsd;
VSD_AUDIOATTRIBUTES_PARMS  vsdAttr;


=== VSD_CLOSE Parameter - pRequest ===
    /* Prime the structure with necessary values */
vsdAttr.ulLength = sizeof (VSD_AUDIOATTRIBUTES_PARMS);
vsdAttr.ulFlags = VSD_BASS;


'''pRequest'''([[01203.htm|PVOID]]) Not used for this command.
    /*---------------------------------------------
    * 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->pfnAUDIOIF(hvsd,
                                VSD_QUERY,
                                VSD_QUERYAUDIOATTRIBUTES,
                                (PVOID)&vsdAttr);


    /* If Bass value is too high then...*/
    if (!rc)
      {
      if (vsdAttr.ulValue > 70)
      {
      }
</pre>


==VSD_QUERYCONNECTOR==
This subcommand of the [[#VSD_QUERY|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 [[MMPM/2 Device Driver Reference:Data Types#VSD_CONNECTOR_PARMS|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 [[#VSDEntry|VSDEntry]] as follows:


=== VSD_CLOSE Return Value - rc ===
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:
=== VSD_QUERYCONNECTOR Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


VSDERR_SUCCESS The command was successful.
=== VSD_QUERYCONNECTOR Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


VSDERR_CANNOT_CLOSE VSD is unable to close the device.
=== VSD_QUERYCONNECTOR Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYCONNECTOR.


VSDERR_HARDWARE A hardware error occurred.
=== VSD_QUERYCONNECTOR Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_CONNECTOR_PARMS|PVSD_CONNECTOR_PARMS]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_CONNECTOR_PARMS|VSD_CONNECTOR_PARMS]] structure.


=== VSD_QUERYCONNECTOR Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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>
    HVSD                  hvsd;
    VSD_CONNECTOR_PARMS    vsdConn;


    vsdConn.ulConn_Type = pConnector->ulConnectorType;
    vsdConn.ulIndex = pConnector->ulConnectorIndex;


    lError = pInstance->pfnNewVSD(hvsd,
                                  VSD_QUERY,
                                  VSD_QUERYCONNECTOR,
                                  (PVOID)&vsdConn);


=== VSD_CLOSE - Syntax ===
    prConnector->ulReturn = vsdConn.fEnabled;
</pre>


This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.
==VSD_QUERYDATATYPE==
This subcommand of the [[#VSD_QUERY|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:
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>


=== VSD_QUERYDATATYPE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


'''hvsd'''([[00810.htm|HVSD]]) Handle to the VSD to be closed.
=== VSD_QUERYDATATYPE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_CLOSE.
=== VSD_QUERYDATATYPE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYDATATYPE.


'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.
=== VSD_QUERYDATATYPE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|PVSD_AUDIODATATYPE_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|VSD_AUDIODATATYPE_PARMS]] structure.


'''pRequest'''([[01203.htm|PVOID]]) Not used for this command.
=== VSD_QUERYDATATYPE Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:
=== VSD_QUERYDATATYPE - Remarks ===
 
This command is typically sent by applications which need to determine if the VSD supports a particular datatype.
VSDERR_SUCCESS The command was successful.
 
VSDERR_CANNOT_CLOSE VSD is unable to close the device.
 
VSDERR_HARDWARE A hardware error occurred.


=== VSD_QUERYDATATYPE - Example Code ===
The following code illustrates the use of VSD_QUERYDATATYPE:
<pre>
HVSD                      hvsd;
VSD_AUDIODATATYPE_PARMS    AudioCaps;


  /*---------------------------------------
  * Tell the VSD that we want to enable a
  * connector.
  *---------------------------------------*/
  rc =  pInstance->pfnNewVSD( hvsd ,
                              VSD_QUERY,
                              VSD_QUERYDATATYPE,
                              (PVOID ) &AudioCaps );


  if ( rc )
      {
        rc = MCIERR_INVALID_CONNECTION ;
      return (rc);
      }
  else
      {
      rc = MCIERR_SUCCESS;
      }


  return ( rc );


=== VSD_CLOSE - Remarks ===
      } /* TestConnection */
</pre>


The ''hvsd''handle is no longer valid after this command is issued.
==VSD_QUERYMIXCONNECTIONS==
This subcommand of the [[#VSD_QUERY|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 [[Audio Sample for Vendor-Specific Drivers]] and [[MMPM/2 Device Driver Reference:IOCtl Functions#Mixer IOCtl Functions Introduction|Mixer IOCtl Functions Introduction]]


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_QUERYMIXCONNECTIONS Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_QUERYMIXCONNECTIONS Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


=== VSD_CLOSE - Example Code ===
=== VSD_QUERYMIXCONNECTIONS Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYMIXCONNECTIONS.


The following code illustrates how to close a VSD.
=== VSD_QUERYMIXCONNECTIONS Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|PLINECONNECTIONS]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure.


<pre class="western">HVSD    hvsd;
=== VSD_QUERYMIXCONNECTIONS Return Value - rc ===
    ULONG   rc;
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


    rc = pInstance -&gt;pfnAUDIOIF(  hvsd,
=== VSD_QUERYMIXCONNECTIONS - Remarks ===
                                  VSD_CLOSE,
The ''ulConnections'' field of the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure returns the particular output that a line is routed to. The ''ulLine'' field of the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure must contain a valid line on input. For more information on the values for ''ulLine'' and ''ulConnections'', see the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure.
                                  0,
                                  0 );
    return (rc);</pre>


=== VSD_QUERYMIXCONNECTIONS - Example Code ===
The following code illustrates how to query the output that a particular line is routed to.
<pre>
  HVSD              hvsd;
  LINECONNECTIONS  LineCon;


/* Find out the setting for the synth. */


  LineCon.ulLine = SOURCE_SYNTHESIZER;


=== VSD_CLOSE - Topics ===
  LineCon.ulLength = sizeof(MIXERLINEINFO);
/* Ask VSD for the capabilities of this line. */


Select an item:
  rc = pInstance->(hvsd,
                  VSD_QUERY,
                  VSD_QUERYMIXCONNECTIONS,
                  (PVOID)&LineCon);


<pre class="western">Syntax
/* Are we connected to the amp or record outputs... */
Returns
Remarks
Example Code
Glossary </pre>


  if (LineCon.ulConnection & (SINK_SPEAKERS))
    {
    pMixParms->ulReturn = MCI_OUTPUT_AMP;
    }
  else
    {
    pMixParms->ulReturn = MCI_OUTPUT_DIGITALAUDIO;
    }
</pre>


==VSD_QUERYMIXCONTROL==
This subcommand of the [[#VSD_QUERY|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 [[Audio Sample for Vendor-Specific Drivers]] and [[MMPM/2 Device Driver Reference:IOCtl Functions#Mixer IOCtl Functions Introduction|Mixer IOCtl Functions Introduction]]


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


=== VSD_DDCMD ===
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_QUERYMIXCONTROL Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


-----
=== VSD_QUERYMIXCONTROL Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


Select an item:
=== VSD_QUERYMIXCONTROL Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYMIXCONTROL.


<pre class="western">Syntax
=== VSD_QUERYMIXCONTROL Parameter - pRequest ===
Returns
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|PMIXERCONTROL]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|MIXERCONTROL]] structure.
Remarks
Glossary </pre>


-----
=== VSD_QUERYMIXCONTROL Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


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.
=== VSD_QUERYMIXCONTROL - Remarks ===
The ''ulLine'' field of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|MIXERCONTROL]] structure must be filled in with one of the VSD sources/sinks in the low-order byte of the low word.


This command is sent using [[00235.htm|VSDEntry]]as follows:
The ''ulControl'' field of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|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.


<pre class="western">   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>
=== VSD_QUERYMIXCONTROL - Example Code ===
The following code illustrates how to query the settings of audio attributes for a particular connector.
<pre>
  HVSD          hvsd;
  MIXERCONTROL  MixerControl;
  USHORT        usBass;


/* Find out the setting for the synth. */


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.
  MixerControl.ulLine = SOURCE_SYNTHESIZER;


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_DDCMD.
/* Ask VSD what is the current setting of the connector. */


'''ulFlags'''([[00998.htm|ULONG]]) The following flags (subcommands) are defined for this command:
  MixerControl.ulControl = MIX_BASS;
  rc = pInstance->(hvsd,
                  VSD_QUERY,
                  VSD_QUERYMIXCONTROL,
                  (PVOID)&MixerControl);


DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. ''pRequest''is a pointer to the [[00759.htm|DDCMDCONTROL]]structure.
    usBass = (MixControl.ulSetting)


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.
    }
</pre>


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.
==VSD_QUERYMIXLINE==
This subcommand of the [[#VSD_QUERY|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 [[Audio Sample for Vendor-Specific Drivers]] and [[MMPM/2 Device Driver Reference:IOCtl Functions#Mixer IOCtl Functions Introduction|Mixer IOCtl Functions Introduction]]


''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


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.
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest''is a pointer to [[00793.htm|DDCMDSETUP]]structure.
=== VSD_QUERYMIXLINE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


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.
=== VSD_QUERYMIXLINE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERY.


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.
=== VSD_QUERYMIXLINE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYMIXLINE.


''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.
=== VSD_QUERYMIXLINE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#MIXERLINEINFO|PMIXERLINEINFO]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#MIXERLINEINFO|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.


'''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_QUERYMIXLINE Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


'''rc'''([[00998.htm|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.
=== VSD_QUERYMIXLINE - Example Code ===
The following code illustrates how to query the supported audio attributes from a mixer connector.
<pre>
HVSD              hvsd;
MIXERLINEINFO      mixerinfo;
  mixerinfo.ulLine = SYNTHESIZER_INPUT;
  mixerinfo.ulLength = sizeof(MIXERLINEINFO);
      rc = pInstance->pfnAUDIOIF( hsvd,
                                  VSD_QUERY,
                                  VSD_QUERYMIXLINE,
                                  (PVOID) &mixerinfo);


  if(!rc)
      if(mixerinfo.ulSupport & MIX_VOLUME)
          {
          /* process volume */
          }


        }  /* If no errors */
</pre>


=== VSD_QUERYMONITOR ===
This subcommand of the [[#VSD_QUERY|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 [[#VSDEntry|VSDEntry]] as follows:


=== VSD_DDCMD Parameter - hvsd ===
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.
=== VSD_QUERYMONITOR Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD instance.


=== VSD_QUERYMONITOR Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


=== VSD_QUERYMONITOR Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYMONITOR.


=== VSD_QUERYMONITOR Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|PULONG]]) Output.


=== VSD_QUERYMONITOR Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.


=== VSD_DDCMD Parameter - ulFunc ===
=== VSD_QUERYMONITOR - Example Code ===
The following code illustrates how to query the state of monitoring.
<pre>
rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
                          VSD_QUERY,
                          VSD_QUERYMONITOR,
                          (PVOID)&pStat->ulReturn);
</pre>


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_DDCMD.
==VSD_QUERYSTATUSLEVEL==
This subcommand of the [[#VSD_QUERY|VSD_QUERY]] command queries the status of the audio input level (percentage). This command is optional.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_QUERYSTATUSLEVEL Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_QUERYSTATUSLEVEL Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


=== VSD_DDCMD Parameter - ulFlags ===
=== VSD_QUERYSTATUSLEVEL Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYSTATUSLEVEL.


'''ulFlags'''([[00998.htm|ULONG]]) The following flags (subcommands) are defined for this command:
=== VSD_QUERYSTATUSLEVEL Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|PULONG]]) Current level of device.


DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. ''pRequest''is a pointer to the [[00759.htm|DDCMDCONTROL]]structure.
=== VSD_QUERYSTATUSLEVEL Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Error code indicating success or the type of failure:
*VSDERR_SUCCESS
:The command was successful.


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.
==VSD_QUERYVOLUME==
This subcommand of the [[#VSD_QUERY|VSD_QUERY]] command queries the volume level. The volume is returned as a percentage between 0% and 100%


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.
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


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.
=== VSD_QUERYVOLUME Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest''is a pointer to [[00793.htm|DDCMDSETUP]]structure.
=== VSD_QUERYVOLUME Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_QUERY|VSD_QUERY]].


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.
=== VSD_QUERYVOLUME Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_QUERYVOLUME.


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.
=== VSD_QUERYVOLUME Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_VOLUME_PARMS|PVSD_VOLUME_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_VOLUME_PARMS|VSD_VOLUME_PARMS]] structure.


''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.
=== VSD_QUERYVOLUME Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 [[MMPM/2 Device Driver Reference:Data Types#VSD_VOLUME_PARMS|VSD_VOLUME_PARMS]] structure.


=== VSD_QUERYVOLUME - Example Code ===
The following code illustrates how to query audio volume from the VSD.
<pre>
VSD_VOLUME_PARMS  vsdVol;
ULONG              ulVol;
  vsdVol.ulLength = sizeof(VSD_VOLUME_PARMS);
  vsdVol.ulFlags  = ulFlags;


/*------------------------------------------
  *  Ask the VSD to query audio volume.
  *------------------------------------------*/


rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
                          VSD_QUERY,
                          VSD_QUERYVOLUME,
                          (PVOID)&vsdVol);
ulVol = vsdvol.ulVolume;
</pre>


=== VSD_DDCMD Parameter - pRequest ===
==VSD_RESOURCE==
This command can be issued only when the device is opened and is used for resource management.


'''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_RESOURCE is a required command and must be implemented by all VSD writers.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_RESOURCE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_RESOURCE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_RESOURCE.


=== VSD_DDCMD Return Value - rc ===
=== VSD_RESOURCE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


'''rc'''([[00998.htm|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.
=== VSD_RESOURCE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_RESOURCE_PARMS|PVSD_RESOURCE_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_RESOURCE_PARMS|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''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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:


=== VSD_DDCMD - Syntax ===
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.


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.
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).


This command is sent using [[00235.htm|VSDEntry]]as follows:
=== 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>
HVSD  hvsd;
  rc = pInstance->pfnAUDIOIF( hvsd,
                              VSD_RESOURCE,
                              0L,
                              (PVOID)&vsdResourceParms );


<pre class="western">   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>
  pInstance->ulResourcesUsed = vsdResourceParms.ulResUnits;
  pInstance->ulClass = vsdResourceParms.ulClass;
</pre>


==VSD_RESTORE==
This command restores the current state of the device. VSD_RESTORE is a required function and must be implemented by all VSD writers.


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_DDCMD.
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


'''ulFlags'''([[00998.htm|ULONG]]) The following flags (subcommands) are defined for this command:
=== VSD_RESTORE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. ''pRequest''is a pointer to the [[00759.htm|DDCMDCONTROL]]structure.
=== VSD_RESTORE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_RESTORE.


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.
=== VSD_RESTORE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


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.
=== VSD_RESTORE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|PVOID]]) Not used with this command.


''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.
=== VSD_RESTORE Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Error code indicating success or the type of failure:
*VSDERR_SUCCESS
:The command completed successfully.


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.
=== 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).


DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. ''pRequest''is a pointer to [[00793.htm|DDCMDSETUP]]structure.
=== VSD_RESTORE - Example Code ===
The following code illustrates how to activate an audio VSD using VSD_ RESTORE.
<pre>
  ULONG  rc;
  HVSD    hvsd;


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.
      rc = pInstance->pfnAUDIOIF( hvsd,
                                  VSD_RESTORE,
                                  0L,
                                  0 );
      return(rc)
</pre>


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.
==VSD_SAVE==
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 [[#VSDEntry|VSDEntry]] as follows:


''pRequest''is a pointer to [[00769.htm|DDCMDREADWRITE]]structure.
    VSDEntry(hvsd, ulFunc, ulFlags, 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_SAVE Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


'''rc'''([[00998.htm|ULONG]]) Possible error codes vary according to the value of ''ulFlags''.
=== VSD_SAVE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SAVE.


=== VSD_SAVE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) No flags used for this command.


=== VSD_SAVE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|PVOID]]) Not used with this command.


=== VSD_SAVE Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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_DDCMD - Remarks ===
=== VSD_SAVE - Example Code ===
 
The following code illustrates how to deactivate an audio VSD using VSD_ SAVE.
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''
<pre>
  ULONG    rc;
  HVSD    hvsd;


    rc = pInstance->pfnAUDIOIF( hvsd,
                                VSD_SAVE,
                                0L,
                                0 );


    return(rc);
</pre>


==VSD_SET==
This command allows an application to modify the settings of the VSD.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


=== VSD_DDCMD - Topics ===
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


Select an item:
=== VSD_SET Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to VSD.


<pre class="western">Syntax
=== VSD_SET Parameter - ulFunc ===
Returns
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SET.
Remarks
Glossary </pre>


=== VSD_SET Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) The following flags can be used with VSD_SET.
*VSD_SETAUDIOATTRIBUTES
:See [[#VSD_SETAUDIOATTRIBUTES|VSD_SETAUDIOATTRIBUTES]]
*VSD_SETCONNECTOR
:See [[#VSD_SETCONNECTOR|VSD_SETCONNECTOR]]
*VSD_SETDATATYPE
:See [[#VSD_SETDATATYPE|VSD_SETDATATYPE]]
*VSD_SETMIXCONNECTIONS
:See [[#VSD_SETMIXCONNECTIONS|VSD_SETMIXCONNECTIONS]]
*VSD_SETMIXCONTROL
:See [[#VSD_SETMIXCONTROL|VSD_SETMIXCONTROL]]
*VSD_SETMONITOR
: See [[#VSD_SETMONITOR|VSD_SETMONITOR]]
*VSD_SETVOLUME
:See [[#VSD_SETVOLUME|VSD_SETVOLUME]]


=== VSD_SET Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VOID|PVOID]]) Pointer value varies according to the value of ''ulFlags''.


=== VSD_SET Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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 [[#VSD_OPEN|VSD_OPEN]].


=== VSD_GETDEVCAPS ===
=== VSD_SET - Remarks ===
This messages uses flags to specify what to set on the adapter.


==VSD_SETAUDIOATTRIBUTES==
This subcommand of the [[#VSD_SET|VSD_SET]] command sets the audio attribute settings. A valid length must be placed in the ''ulLength'' field of the [[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|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 [[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|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 [[#VSDEntry|VSDEntry]] as follows:


Select an item:
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


<pre class="western">Syntax
=== VSD_SETAUDIOATTRIBUTES Parameter - hvsd ===
Returns
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.
Remarks
Example Code
Glossary </pre>


-----
=== VSD_SETAUDIOATTRIBUTES Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SET.


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.
=== VSD_SETAUDIOATTRIBUTES Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETAUDIOATTRIBUTES.


This command is sent using [[00235.htm|VSDEntry]]as follows:
=== VSD_SETAUDIOATTRIBUTES Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|PVSD_AUDIOATTRIBUTES_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_ AUDIOATTRIBUTES_PARMS|VSD_AUDIOATTRIBUTES_ PARMS]] structure.


<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>
=== VSD_SETAUDIOATTRIBUTES Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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>
VSD_AUDIOATTRIBUTES_PARMS  vsdAttr;


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.
    /* Prime the structure with necessary values */
vsdAttr.ulLength = sizeof (VSD_AUDIOATTRIBUTES_PARMS);
vsdAttr.ulFlags = VSD_BASS;
vsdAttr.ulValue = 100;


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_GETDEVCAPS.
    /*---------------------------------------------
    * Ask the VSD to either set or query an audio
    * attribute. The caller determines whether
    * to set or query via the command variable.
    *---------------------------------------------*/


'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.
    rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
                                VSD_SET,
                                VSD_SETAUDIOATTRIBUTES,
                                (PVOID)&vsdAttr);
</pre>


'''pRequest'''([[01169.htm|PVSD_GETDEVCAPS_PARMS]]) Pointer to the [[01169.htm|VSD_GETDEVCAPS_PARMS]]data structure.
==VSD_SETCONNECTOR==
This subcommand of the [[#VSD_SET|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.


'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:
This command is sent using [[#VSDEntry|VSDEntry]] as follows:


VSDERR_REQUEST_BUF_TOO_SMALL The ''ulLength''in the request packet is too small.
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


VSDERR_MISSING_PARAMETER One or more parameters are missing.
=== VSD_SETCONNECTOR Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


VSDERR_HARDWARE A hardware error occurred.
=== VSD_SETCONNECTOR Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_SET|VSD_SET]].


=== VSD_SETCONNECTOR Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETCONNECTOR.


=== VSD_SETCONNECTOR Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_CONNECTOR_PARMS|PVSD_CONNECTOR_PARMS]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_CONNECTOR_PARMS|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''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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_GETDEVCAPS Parameter - hvsd ===
=== VSD_SETCONNECTOR - Example Code ===
The following code illustrates how to set the state of the connector.
<pre>
    HVSD                  hvsd;
    VSD_CONNECTOR_PARMS    vsdConn;


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.
    vsdConn.ulConn_Type = pConnector->ulConnectorType;
    vsdConn.ulIndex = pConnector->ulConnectorIndex;
    vsdConn.fEnabled = VSD_DISABLE;


    /*--------------------------------------------------
    * Tell the VSD that we want to disable a connector.
    *--------------------------------------------------*/
    lError = pInstance->pfnNewVSD(hvsd,
                                  VSD_SET,
                                  VSD_SETCONNECTOR,
                                  (PVOID)&vsdConn);
</pre>


==VSD_SETDATATYPE==
This subcommand of the [[#VSD_SET|VSD_SET]] command sets the current data type that the device is dealing with.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_GETDEVCAPS Parameter - ulFunc ===
=== VSD_SETDATATYPE Parameter - hvsd ===
 
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.
'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_GETDEVCAPS.


=== VSD_SETDATATYPE Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_SET|VSD_SET]].


=== VSD_SETDATATYPE Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETDATATYPE.


=== VSD_SETDATATYPE Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|PVSD_AUDIODATATYPE_PARMS]]) Input. Pointer to a [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|VSD_AUDIODATATYPE_ PARMS]] structure.


'''Note:''' Every field in the [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|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 [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|VSD_AUDIODATATYPE_PARMS]] structure.


=== VSD_GETDEVCAPS Parameter - ulFlags ===
The ''ulFlags'' field of the [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|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.
 
'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.
 


The [[MMPM/2 Device Driver Reference:Data Types#VSD_AUDIODATATYPE_PARMS|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''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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>
HVSD                    hvsd;
VSD_AUDIODATATYPE_PARMS  AudioDatatype;
PMMAUDIOHEADER          pmmaudioheader;
AudioDatatype.ulDataType = pmmaudioheader->mmXWAVHeader.WAVEHeader.usFormatTag;
AudioDatatype.ulBitsPerSample = pmmaudioheader->mmXWAVHeader.WAVEHeader.usBitsPerSample;
AudioDatatype.ulSamplingRate = pmmaudioheader->mmXWAVHeader.WAVEHeader.usSamplesPerSec;
AudioDatatype.ulChannels = pmmaudioheader->mmXWAVHeader.WAVEHeader.usChannels;
AudioDatatype.ulOperation = VSD_PLAY;
AudioDatatype.ulFlags = VSD_MODE|VSD_CHANNELS|VSD_SAMPLESPERSEC|
                        VSD_OPERATION|VSD_BITSPERSAMPLE;


=== VSD_GETDEVCAPS Parameter - pRequest ===
  rc = pInstance->pfnNewVSD(hvsd,
                            VSD_SET,
                            VSD_SETDATATYPE,
                    (PVOID)&AudioDatatype);
  if(rc)
    {
    return(rc)
    }
</pre>


'''pRequest'''([[01169.htm|PVSD_GETDEVCAPS_PARMS]]) Pointer to the [[01169.htm|VSD_GETDEVCAPS_PARMS]]data structure.
==VSD_SETMIXCONNECTIONS==
This subcommand of the [[#VSD_SET|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 [[Audio Sample for Vendor-Specific Drivers]] and [[MMPM/2 Device Driver Reference:IOCtl Functions#Mixer IOCtl Functions Introduction|Mixer IOCtl Functions Introduction]]


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_SETMIXCONNECTIONS Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_SETMIXCONNECTIONS Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_SET|VSD_SET]].


=== VSD_GETDEVCAPS Return Value - rc ===
=== VSD_SETMIXCONNECTIONS Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETMIXCONNECTIONS.


'''rc'''([[00998.htm|ULONG]]) Error code indicating success or the type of failure:
=== VSD_SETMIXCONNECTIONS Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|PLINECONNECTIONS]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure.


VSDERR_REQUEST_BUF_TOO_SMALL The ''ulLength''in the request packet is too small.
The caller must fill in the ''ulConnections'' and the ''ulLine'' fields of the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure.


VSDERR_MISSING_PARAMETER One or more parameters are missing.
=== VSD_SETMIXCONNECTIONS Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


VSDERR_HARDWARE A hardware error occurred.
=== VSD_SETMIXCONNECTIONS - Example Code ===
The following code illustrates how to route the output of a connector to the internal mixer circuitry.
<pre>
  LINECONNECTIONS  mixinfo;


  mixinfo.ulLine = SOURCE_SYNTHESIZER;
  mixinfo.ulConnection = SINK_SPEAKER;
  rc = pInstance->((HVSD)pInstance->hvsd,
                  VSD_SET,
                  VSD_SETMIXCONNECTIONS,
                  (PVOID)&mixinfo);


  return(rc);
</pre>


==VSD_SETMIXCONTROL==
This subcommand of the [[#VSD_SET|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 [[Audio Sample for Vendor-Specific Drivers]] and [[MMPM/2 Device Driver Reference:IOCtl Functions#Mixer IOCtl Functions Introduction|Mixer IOCtl Functions Introduction]]


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


=== VSD_GETDEVCAPS - Syntax ===
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


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.
=== VSD_SETMIXCONTROL Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


This command is sent using [[00235.htm|VSDEntry]]as follows:
=== VSD_SETMIXCONTROL Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_SET|VSD_SET]].


<pre class="western">    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)</pre>
=== VSD_SETMIXCONTROL Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETMIXCONTROL.


=== VSD_SETMIXCONTROL Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|PMIXERCONTROL]]) A pointer to the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|MIXERCONTROL]] structure.


'''hvsd'''([[00810.htm|HVSD]]) Handle to a VSD.
The ''ulControl'' field of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|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.


'''ulFunc'''([[00998.htm|ULONG]]) Set to VSD_GETDEVCAPS.
=== VSD_SETMIXCONTROL Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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.


'''ulFlags'''([[00998.htm|ULONG]]) No flags used for this command.
=== VSD_SETMIXCONTROL - Example Code ===
The following code illustrates how to query the settings of an audio attributes for a particular connector.
<pre>
  MIXERCONTROL  MixerControl;
  USHORT        usBass;


'''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:
  MixerControl.ulControl = MIX_SUPPORT_VOLUME;
  MixerControl.ulLine = SINK_LINE_OUT;
  MixerControl.ulSetting = 100;


VSDERR_REQUEST_BUF_TOO_SMALL The ''ulLength''in the request packet is too small.
  lError = pInstance->((HVSD)pInstance->hvsd,
                      VSD_SET,
                      VSD_SETMIXCONTROL,
                      (PVOID)&MixerControl);


VSDERR_MISSING_PARAMETER One or more parameters are missing.
  return(lError);
</pre>


VSDERR_HARDWARE A hardware error occurred.
==VSD_SETMONITOR==
This subcommand of the [[#VSD_SET|VSD_SET]] command enables (MCI_TRUE) or disables (MCI_ FALSE) the audio monitor feature of the device.


This command is sent using [[#VSDEntry|VSDEntry]] as follows:


    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)


=== VSD_SETMONITOR Parameter - hvsd ===
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.


=== VSD_SETMONITOR Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_SET|VSD_SET]].


=== VSD_GETDEVCAPS - Remarks ===
=== VSD_SETMONITOR Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETMONITOR.


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.
=== VSD_SETMONITOR Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|PULONG]]) Input. Set to MCI_TRUE or MCI_FALSE.


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_SETMONITOR Return Value - rc ===
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|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>
ULONG    ulSetOn;


  ulSetOn = MCI_TRUE;


  /* Tell the VSD to change monitor status */


  lError = prInstance->pfnAUDIOIF((HVSD)prInstance->pMix->hvsd
                          VSD_SET,
                          VSD_SETMONITOR,
                          (PVOID)lSetOn);
</pre>


=== VSD_GETDEVCAPS - Example Code ===
==VSD_SETVOLUME==


The following code illustrates how to determine device capabilities for a VSD.
This subcommand of the [[#VSD_SET|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.


<pre class="western">  HVSD                  hvsd;
This command is sent using [[#VSDEntry|VSDEntry]] as follows:
  VSD_GETDEVCAPS_PARMS  vsdDevCaps;


  rc = pInstance-&gt;pfnAUDIOIF( hvsd,
    VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
                              VSD_GETDEVCAPS
                              0,
                              (PVOID) &amp;vsdDevCaps );


  if (!rc)
=== VSD_SETVOLUME Parameter - hvsd ===
    {
'''hvsd''' ([[MMPM/2 Device Driver Reference:Data Types#HVSD|HVSD]]) Handle to a VSD.
    /* 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 Parameter - ulFunc ===
'''ulFunc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to [[#VSD_SET|VSD_SET]].


=== VSD_SETVOLUME Parameter - ulFlags ===
'''ulFlags''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Set to VSD_SETVOLUME.


=== VSD_SETVOLUME Parameter - pRequest ===
'''pRequest''' ([[MMPM/2 Device Driver Reference:Data Types#VSD_VOLUME_PARMS|PVSD_VOLUME_PARMS]]) Pointer to the [[MMPM/2 Device Driver Reference:Data Types#VSD_VOLUME_PARMS|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 - Syntax ===
=== VSD_SETVOLUME Return Value - rc ===
 
'''rc''' ([[MMPM/2 Device Driver Reference:Data Types#ULONG|ULONG]]) Error codes indicating success or the type of failure:
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.
*VSDERR_SUCCESS
 
:The command was successful.
This command is sent using [[00235.htm|VSDEntry]]as follows:
*VSDERR_VOL_OUT_OF_RANGE
 
:Invalid volume level.
<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 ===
=== VSD_SETVOLUME - Example Code ===
The following code illustrates how to set the volume on an audio VSD.
The following code illustrates how to set the volume on an audio VSD.
 
<pre>
<pre class="western">VSD_VOLUME_PARMS  vsdVol;
VSD_VOLUME_PARMS  vsdVol;
   vsdVol.ulVolume = pInstance-&gt;ulVolume;
   vsdVol.ulVolume = pInstance->ulVolume;
   vsdVol.ulMasterAudio  = pInstance-&gt;ulMasterVolume;
   vsdVol.ulMasterAudio  = pInstance->ulMasterVolume;
   vsdVol.fMute = pInstance-&gt;fMute;
   vsdVol.fMute = pInstance->fMute;
   vsdVol.ulVectoredVolume  = pInstance-&gt;ulTime;
   vsdVol.ulVectoredVolume  = pInstance->ulTime;
   vsdVol.ulFlags  = VSD_VOLUME | VSD_MASTERVOLUME;
   vsdVol.ulFlags  = VSD_VOLUME | VSD_MASTERVOLUME;




   lError = prInstance-&gt;pfnAUDIOIF((HVSD)prInstance-&gt;pMix-&gt;hvsd
   lError = prInstance->pfnAUDIOIF((HVSD)prInstance->pMix->hvsd
                           VSD_SET,
                           VSD_SET,
                           VSD_SETVOLUME,
                           VSD_SETVOLUME,
                           (PVOID)&amp;vsdVol);</pre>
                           (PVOID)&vsdVol);
 
</pre>
 
 
 
=== VSD_SETVOLUME - Topics ===
 
Select an item:
 
<pre class="western">Syntax
Returns
Example Code
Glossary </pre>
 


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

Revision as of 22:24, 6 April 2016

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 VSDEntry entry point.

VSDEntry

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.

#define INCL_AUDIO_VSD
#include <vsdcmds.h>
#include <os2mixer.h>

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);


VSDEntry Parameter - hvsd

hvsd (HVSD) - input This parameter is the handle to the VSD instance.

VSDEntry Parameter - ulFunc

ulFunc (ULONG) - input The VSD command to be issued. The following commands are supported for audio VSDs.

/-------------------------------------------------------------\
|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)                    |
\-------------------------------------------------------------/

VSDEntry Parameter - ulFlags

ulFlags (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 (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 (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.

VSD_CLOSE

This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_CLOSE Parameter - hvsd

hvsd (HVSD) Handle to the VSD to be closed.

VSD_CLOSE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_CLOSE.

VSD_CLOSE Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_CLOSE Parameter - pRequest

pRequest (PVOID) Not used for this command.

VSD_CLOSE Return Value - rc

rc (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.

HVSD     hvsd;
    ULONG    rc;

    rc = pInstance ->pfnAUDIOIF(  hvsd,
                                  VSD_CLOSE,
                                  0,
                                  0 );
    return (rc);

VSD_DDCMD

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 VSDEntry as follows:

  VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_DDCMD Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_DDCMD Parameter - ulFunc

ulFunc (ULONG) Set to VSD_DDCMD.

VSD_DDCMD Parameter - ulFlags

ulFlags (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 DDCMDCONTROL structure.

DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. pRequest is a pointer to 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 MSG_REPORTINT structure to the pSHDEntryPoint in DDCMDREGISTER to inform the caller.

pRequest is a pointer to DDCMDREADWRITE structure.

DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. pRequest is a pointer to DDCMDREGISTER structure.

DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. pRequest is a pointer to 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 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 MSG_REPORTINT structure to the pSHDEntryPoint in DDCMDREGISTER to inform the caller.

pRequest is a pointer to DDCMDREADWRITE structure.

VSD_DDCMD Parameter - pRequest

pRequest (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 (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 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 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_GETDEVCAPS

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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_GETDEVCAPS Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_GETDEVCAPS Parameter - ulFunc

ulFunc (ULONG) Set to VSD_GETDEVCAPS.

VSD_GETDEVCAPS Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_GETDEVCAPS Parameter - pRequest

pRequest (PVSD_GETDEVCAPS_PARMS) Pointer to the VSD_GETDEVCAPS_PARMS data structure.

VSD_GETDEVCAPS Return Value - rc

rc (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 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.

  HVSD                   hvsd;
  VSD_GETDEVCAPS_PARMS   vsdDevCaps;

  rc = pInstance->pfnAUDIOIF(  hvsd,
                               VSD_GETDEVCAPS
                               0,
                               (PVOID) &vsdDevCaps );

  if (!rc)
     {
    /* If the VSD doesn't support volume  */

    if( !vsdDevCaps.bSupports[ DC_HASVOLUME] )
       {
       return ( rc );
       }

VSD_ESCAPE

This optional command sends a buffer to the driver.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_ESCAPE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_ESCAPE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_ESCAPE.

VSD_ESCAPE Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_ESCAPE Parameter - pRequest

pRequest (PVSD_ESCAPE_PARMS) A pointer to the VSD_ESCAPE_PARMS structure.

VSD_ESCAPE Return Value - rc

rc (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_INSERTSETTINGSPAGE

This command enables a VSD to insert device-specific settings pages into the system configuration application.

VSD_INSERTSETTINGSPAGE Parameter - hvsd

hvsd (HVSD) Handle to a VSD instance.

VSD_INSERTSETTINGSPAGE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_INSERTSETTINGSPAGE.

VSD_INSERTSETTINGSPAGE Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_INSERTSETTINGSPAGE Parameter - pRequest

pRequest (PMCI_DEVICESETTINGS_PARMS) Pointer to the MCI_DEVICESETTINGS_ PARMS data structure.

VSD_INSERTSETTINGSPAGE Return Value - hwndRC

hwndRC (HWND) The return code contains the handle to a settings page or zero if no page is inserted.

VSD_OPEN

This command opens the device driver and returns a VSD handle or (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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_OPEN Parameter - hvsd

hvsd (HVSD) Not used.

VSD_OPEN Parameter - ulFunc

ulFunc (ULONG) Set to VSD_OPEN.

VSD_OPEN Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_OPEN Parameter - pRequest

pRequest (PVSD_OPEN_PARMS) Pointer to the VSD_OPEN_PARMS data structure.

VSD_OPEN Return Value - rc

rc (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 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 VSD_AUDIOOPEN_PARMS structure with a valid data subtype.

VSD_OPEN - Example Code

The following code illustrates how to open an audio VSD.

 VSD_OPEN_PARMS        vsdOpenParms;
 VSD_AUDIOOPEN_PARMS   vsdData;

 vsdData.ulLength = sizeof(VSD_AUDIOOPEN_PARMS);
 vsdData.ulFlags = 0;
 vsdData.ulSamplingRate       = pInstance->lSRate;
 vsdData.ulBitsPerSample      = pInstance->lBitsPerSRate;
 vsdData.ulChannels           = pInstance->sChannels;
 vsdData.ulDataType           = pInstance->sMode;
 vsdData.ulDeviceID           = pInstance->ulDeviceID;
 vsdData.ulOperation          = pInstance->ulOperation;
 vsdOpenParms.pDevInfo = (PVOID)&vsdData;


     vsdOpenParms.ulLength = sizeof(VSD_OPEN_PARMS);
     memmove(&vsdOpenParms.szPDDName,
             pInstance->szDeviceName,
             strlen(pInstance->szDeviceName));
       /* Open the audio VSD */
     rc = pInstance->pfnAUDIOIF(0,
                                VSD_OPEN,
                                0L
                                (PVOID)&vsdOpenParms);
     if (!rc)
        }
        pInstance->hvsd = vsdOpenParms.hvsd;
        {

VSD_QUERY

This command allows an application to query the status of the VSD.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERY Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERY Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERY Parameter - ulFlags

ulFlags (ULONG) The following flags can be used with VSD_QUERY:

VSD_QUERY Return Value - pRequest

pRequest (PVOID) Pointer varies according to ulFlags.

VSD_QUERY Return Value - rc

rc (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_QUERYAUDIOATTRIBUTES

This subcommand of the VSD_QUERY command queries the current audio settings and capabilities. A valid length must be placed in the ulLength field of the VSD_AUDIOATTRIBUTES_PARMS structure and the audio setting (such as treble, bass, and so on) must be placed in the ulFlags field of the VSD_ AUDIOATTRIBUTES_PARMS structure.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYAUDIOATTRIBUTES Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYAUDIOATTRIBUTES Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYAUDIOATTRIBUTES Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYAUDIOATTRIBUTES.

VSD_QUERYAUDIOATTRIBUTES Parameter - pRequest

pRequest (PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMS structure.

VSD_QUERYAUDIOATTRIBUTES Return Value - rc

rc (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.

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->pfnAUDIOIF(hvsd,
                                VSD_QUERY,
                                VSD_QUERYAUDIOATTRIBUTES,
                                (PVOID)&vsdAttr);

    /* If Bass value is too high then...*/
    if (!rc)
       {
       if (vsdAttr.ulValue > 70)
       {
       }

VSD_QUERYCONNECTOR

This subcommand of the 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 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 VSDEntry as follows:

VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYCONNECTOR Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYCONNECTOR Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYCONNECTOR Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYCONNECTOR.

VSD_QUERYCONNECTOR Parameter - pRequest

pRequest (PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMS structure.

VSD_QUERYCONNECTOR Return Value - rc

rc (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.

    HVSD                   hvsd;
    VSD_CONNECTOR_PARMS    vsdConn;

    vsdConn.ulConn_Type = pConnector->ulConnectorType;
    vsdConn.ulIndex = pConnector->ulConnectorIndex;

    lError = pInstance->pfnNewVSD(hvsd,
                                  VSD_QUERY,
                                  VSD_QUERYCONNECTOR,
                                  (PVOID)&vsdConn);

    prConnector->ulReturn = vsdConn.fEnabled;

VSD_QUERYDATATYPE

This subcommand of the 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 VSDEntry as follows:

VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYDATATYPE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYDATATYPE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYDATATYPE Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYDATATYPE.

VSD_QUERYDATATYPE Parameter - pRequest

pRequest (PVSD_AUDIODATATYPE_PARMS) Pointer to the VSD_AUDIODATATYPE_PARMS structure.

VSD_QUERYDATATYPE Return Value - rc

rc (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:

 HVSD                       hvsd;
 VSD_AUDIODATATYPE_PARMS    AudioCaps;

   /*---------------------------------------
   * Tell the VSD that we want to enable a
   * connector.
   *---------------------------------------*/
   rc =  pInstance->pfnNewVSD( hvsd ,
                               VSD_QUERY,
                               VSD_QUERYDATATYPE,
                               (PVOID ) &AudioCaps );

   if ( rc )
      {
        rc = MCIERR_INVALID_CONNECTION ;
      return (rc);
      }
   else
      {
      rc = MCIERR_SUCCESS;
      }

   return ( rc );

      } /* TestConnection */

VSD_QUERYMIXCONNECTIONS

This subcommand of the 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 Audio Sample for Vendor-Specific Drivers and Mixer IOCtl Functions Introduction

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYMIXCONNECTIONS Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYMIXCONNECTIONS Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYMIXCONNECTIONS Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYMIXCONNECTIONS.

VSD_QUERYMIXCONNECTIONS Parameter - pRequest

pRequest (PLINECONNECTIONS) A pointer to the LINECONNECTIONS structure.

VSD_QUERYMIXCONNECTIONS Return Value - rc

rc (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 LINECONNECTIONS structure returns the particular output that a line is routed to. The ulLine field of the LINECONNECTIONS structure must contain a valid line on input. For more information on the values for ulLine and ulConnections, see the LINECONNECTIONS structure.

VSD_QUERYMIXCONNECTIONS - Example Code

The following code illustrates how to query the output that a particular line is routed to.

  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->(hvsd,
                   VSD_QUERY,
                   VSD_QUERYMIXCONNECTIONS,
                   (PVOID)&LineCon);

 /* Are we connected to the amp or record outputs... */

  if (LineCon.ulConnection & (SINK_SPEAKERS))
     {
     pMixParms->ulReturn = MCI_OUTPUT_AMP;
     }
  else
     {
     pMixParms->ulReturn = MCI_OUTPUT_DIGITALAUDIO;
     }

VSD_QUERYMIXCONTROL

This subcommand of the 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 Audio Sample for Vendor-Specific Drivers and Mixer IOCtl Functions Introduction

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYMIXCONTROL Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYMIXCONTROL Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYMIXCONTROL Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYMIXCONTROL.

VSD_QUERYMIXCONTROL Parameter - pRequest

pRequest (PMIXERCONTROL) A pointer to the MIXERCONTROL structure.

VSD_QUERYMIXCONTROL Return Value - rc

rc (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 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 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.

  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->(hvsd,
                   VSD_QUERY,
                   VSD_QUERYMIXCONTROL,
                   (PVOID)&MixerControl);

     usBass = (MixControl.ulSetting)

     }

VSD_QUERYMIXLINE

This subcommand of the 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 Audio Sample for Vendor-Specific Drivers and Mixer IOCtl Functions Introduction

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYMIXLINE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYMIXLINE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYMIXLINE Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYMIXLINE.

VSD_QUERYMIXLINE Parameter - pRequest

pRequest (PMIXERLINEINFO) A pointer to the 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 (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.

HVSD               hvsd;
MIXERLINEINFO      mixerinfo;
  mixerinfo.ulLine = SYNTHESIZER_INPUT;
  mixerinfo.ulLength = sizeof(MIXERLINEINFO);
      rc = pInstance->pfnAUDIOIF( hsvd,
                                  VSD_QUERY,
                                  VSD_QUERYMIXLINE,
                                  (PVOID) &mixerinfo);

   if(!rc)
      if(mixerinfo.ulSupport & MIX_VOLUME)
          {
          /* process volume */
          }

        }  /* If no errors */

VSD_QUERYMONITOR

This subcommand of the 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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYMONITOR Parameter - hvsd

hvsd (HVSD) Handle to a VSD instance.

VSD_QUERYMONITOR Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYMONITOR Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYMONITOR.

VSD_QUERYMONITOR Parameter - pRequest

pRequest (PULONG) Output.

VSD_QUERYMONITOR Return Value - rc

rc (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.

rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
                           VSD_QUERY,
                           VSD_QUERYMONITOR,
                           (PVOID)&pStat->ulReturn);

VSD_QUERYSTATUSLEVEL

This subcommand of the VSD_QUERY command queries the status of the audio input level (percentage). This command is optional.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYSTATUSLEVEL Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYSTATUSLEVEL Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYSTATUSLEVEL Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYSTATUSLEVEL.

VSD_QUERYSTATUSLEVEL Parameter - pRequest

pRequest (PULONG) Current level of device.

VSD_QUERYSTATUSLEVEL Return Value - rc

rc (ULONG) Error code indicating success or the type of failure:

  • VSDERR_SUCCESS
The command was successful.

VSD_QUERYVOLUME

This subcommand of the VSD_QUERY command queries the volume level. The volume is returned as a percentage between 0% and 100%

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_QUERYVOLUME Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_QUERYVOLUME Parameter - ulFunc

ulFunc (ULONG) Set to VSD_QUERY.

VSD_QUERYVOLUME Parameter - ulFlags

ulFlags (ULONG) Set to VSD_QUERYVOLUME.

VSD_QUERYVOLUME Parameter - pRequest

pRequest (PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMS structure.

VSD_QUERYVOLUME Return Value - rc

rc (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 VSD_VOLUME_PARMS structure.

VSD_QUERYVOLUME - Example Code

The following code illustrates how to query audio volume from the VSD.

VSD_VOLUME_PARMS   vsdVol;
ULONG              ulVol;
   vsdVol.ulLength = sizeof(VSD_VOLUME_PARMS);
   vsdVol.ulFlags  = ulFlags;

 /*------------------------------------------
  *  Ask the VSD to query audio volume.
  *------------------------------------------*/

rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
                           VSD_QUERY,
                           VSD_QUERYVOLUME,
                           (PVOID)&vsdVol);
ulVol = vsdvol.ulVolume;

VSD_RESOURCE

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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_RESOURCE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_RESOURCE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_RESOURCE.

VSD_RESOURCE Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_RESOURCE Parameter - pRequest

pRequest (PVSD_RESOURCE_PARMS) Pointer to the 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 (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.

 HVSD   hvsd;
  rc = pInstance->pfnAUDIOIF( hvsd,
                              VSD_RESOURCE,
                              0L,
                              (PVOID)&vsdResourceParms );

  pInstance->ulResourcesUsed = vsdResourceParms.ulResUnits;
  pInstance->ulClass = vsdResourceParms.ulClass;

VSD_RESTORE

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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_RESTORE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_RESTORE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_RESTORE.

VSD_RESTORE Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_RESTORE Parameter - pRequest

pRequest (PVOID) Not used with this command.

VSD_RESTORE Return Value - rc

rc (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.

   ULONG   rc;
   HVSD    hvsd;

       rc = pInstance->pfnAUDIOIF( hvsd,
                                   VSD_RESTORE,
                                   0L,
                                   0 );
       return(rc)

VSD_SAVE

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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SAVE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SAVE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SAVE.

VSD_SAVE Parameter - ulFlags

ulFlags (ULONG) No flags used for this command.

VSD_SAVE Parameter - pRequest

pRequest (PVOID) Not used with this command.

VSD_SAVE Return Value - rc

rc (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.

   ULONG    rc;
   HVSD    hvsd;

     rc = pInstance->pfnAUDIOIF( hvsd,
                                 VSD_SAVE,
                                 0L,
                                 0 );

     return(rc);

VSD_SET

This command allows an application to modify the settings of the VSD.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SET Parameter - hvsd

hvsd (HVSD) Handle to VSD.

VSD_SET Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SET Parameter - ulFlags

ulFlags (ULONG) The following flags can be used with VSD_SET.

  • VSD_SETAUDIOATTRIBUTES
See VSD_SETAUDIOATTRIBUTES
  • VSD_SETCONNECTOR
See VSD_SETCONNECTOR
  • VSD_SETDATATYPE
See VSD_SETDATATYPE
  • VSD_SETMIXCONNECTIONS
See VSD_SETMIXCONNECTIONS
  • VSD_SETMIXCONTROL
See VSD_SETMIXCONTROL
  • VSD_SETMONITOR
See VSD_SETMONITOR
  • VSD_SETVOLUME
See VSD_SETVOLUME

VSD_SET Parameter - pRequest

pRequest (PVOID) Pointer value varies according to the value of ulFlags.

VSD_SET Return Value - rc

rc (ULONG) Error code indicating success or the type of failure:

  • VSDERR_INVALID_HVSD
The hvsd(VSD handle) is not valid. Verify that the hvsdmatches the one provided on the VSD_OPEN.

VSD_SET - Remarks

This messages uses flags to specify what to set on the adapter.

VSD_SETAUDIOATTRIBUTES

This subcommand of the VSD_SET command sets the audio attribute settings. A valid length must be placed in the ulLength field of the 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 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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETAUDIOATTRIBUTES Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETAUDIOATTRIBUTES Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETAUDIOATTRIBUTES Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETAUDIOATTRIBUTES.

VSD_SETAUDIOATTRIBUTES Parameter - pRequest

pRequest (PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMS structure.

VSD_SETAUDIOATTRIBUTES Return Value - rc

rc (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.

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->pfnAUDIOIF((HVSD)pInstance->hvsd,
                                VSD_SET,
                                VSD_SETAUDIOATTRIBUTES,
                                (PVOID)&vsdAttr);

VSD_SETCONNECTOR

This subcommand of the 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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETCONNECTOR Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETCONNECTOR Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETCONNECTOR Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETCONNECTOR.

VSD_SETCONNECTOR Parameter - pRequest

pRequest (PVSD_CONNECTOR_PARMS) A pointer to the 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 (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.

    HVSD                   hvsd;
    VSD_CONNECTOR_PARMS    vsdConn;

    vsdConn.ulConn_Type = pConnector->ulConnectorType;
    vsdConn.ulIndex = pConnector->ulConnectorIndex;
    vsdConn.fEnabled = VSD_DISABLE;

    /*--------------------------------------------------
     * Tell the VSD that we want to disable a connector.
     *--------------------------------------------------*/
    lError = pInstance->pfnNewVSD(hvsd,
                                  VSD_SET,
                                  VSD_SETCONNECTOR,
                                  (PVOID)&vsdConn);

VSD_SETDATATYPE

This subcommand of the VSD_SET command sets the current data type that the device is dealing with.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETDATATYPE Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETDATATYPE Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETDATATYPE Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETDATATYPE.

VSD_SETDATATYPE Parameter - pRequest

pRequest (PVSD_AUDIODATATYPE_PARMS) Input. Pointer to a VSD_AUDIODATATYPE_ PARMS structure.

Note: Every field in the 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 VSD_AUDIODATATYPE_PARMS structure.

The ulFlags field of the 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 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 (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.

HVSD                     hvsd;
VSD_AUDIODATATYPE_PARMS  AudioDatatype;
PMMAUDIOHEADER           pmmaudioheader;
AudioDatatype.ulDataType = pmmaudioheader->mmXWAVHeader.WAVEHeader.usFormatTag;
AudioDatatype.ulBitsPerSample = pmmaudioheader->mmXWAVHeader.WAVEHeader.usBitsPerSample;
AudioDatatype.ulSamplingRate = pmmaudioheader->mmXWAVHeader.WAVEHeader.usSamplesPerSec;
AudioDatatype.ulChannels = pmmaudioheader->mmXWAVHeader.WAVEHeader.usChannels;
AudioDatatype.ulOperation = VSD_PLAY;
AudioDatatype.ulFlags = VSD_MODE|VSD_CHANNELS|VSD_SAMPLESPERSEC|
                        VSD_OPERATION|VSD_BITSPERSAMPLE;

   rc = pInstance->pfnNewVSD(hvsd,
                             VSD_SET,
                             VSD_SETDATATYPE,
                    (PVOID)&AudioDatatype);
   if(rc)
     {
     return(rc)
     }

VSD_SETMIXCONNECTIONS

This subcommand of the 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 Audio Sample for Vendor-Specific Drivers and Mixer IOCtl Functions Introduction

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETMIXCONNECTIONS Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETMIXCONNECTIONS Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETMIXCONNECTIONS Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETMIXCONNECTIONS.

VSD_SETMIXCONNECTIONS Parameter - pRequest

pRequest (PLINECONNECTIONS) A pointer to the LINECONNECTIONS structure.

The caller must fill in the ulConnections and the ulLine fields of the LINECONNECTIONS structure.

VSD_SETMIXCONNECTIONS Return Value - rc

rc (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.

  LINECONNECTIONS   mixinfo;

  mixinfo.ulLine = SOURCE_SYNTHESIZER;
  mixinfo.ulConnection = SINK_SPEAKER;
  rc = pInstance->((HVSD)pInstance->hvsd,
                   VSD_SET,
                   VSD_SETMIXCONNECTIONS,
                   (PVOID)&mixinfo);

  return(rc);

VSD_SETMIXCONTROL

This subcommand of the 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 Audio Sample for Vendor-Specific Drivers and Mixer IOCtl Functions Introduction

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETMIXCONTROL Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETMIXCONTROL Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETMIXCONTROL Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETMIXCONTROL.

VSD_SETMIXCONTROL Parameter - pRequest

pRequest (PMIXERCONTROL) A pointer to the MIXERCONTROL structure.

The ulControl field of the 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 (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.

  MIXERCONTROL   MixerControl;
  USHORT         usBass;


  MixerControl.ulControl = MIX_SUPPORT_VOLUME;
  MixerControl.ulLine = SINK_LINE_OUT;
  MixerControl.ulSetting = 100;

  lError = pInstance->((HVSD)pInstance->hvsd,
                      VSD_SET,
                      VSD_SETMIXCONTROL,
                      (PVOID)&MixerControl);

   return(lError);

VSD_SETMONITOR

This subcommand of the VSD_SET command enables (MCI_TRUE) or disables (MCI_ FALSE) the audio monitor feature of the device.

This command is sent using VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETMONITOR Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETMONITOR Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETMONITOR Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETMONITOR.

VSD_SETMONITOR Parameter - pRequest

pRequest (PULONG) Input. Set to MCI_TRUE or MCI_FALSE.

VSD_SETMONITOR Return Value - rc

rc (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.

ULONG    ulSetOn;

   ulSetOn = MCI_TRUE;

   /* Tell the VSD to change monitor status */

   lError = prInstance->pfnAUDIOIF((HVSD)prInstance->pMix->hvsd
                           VSD_SET,
                           VSD_SETMONITOR,
                           (PVOID)lSetOn);

VSD_SETVOLUME

This subcommand of the 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 VSDEntry as follows:

   VSDEntry(hvsd, ulFunc, ulFlags, pRequest)

VSD_SETVOLUME Parameter - hvsd

hvsd (HVSD) Handle to a VSD.

VSD_SETVOLUME Parameter - ulFunc

ulFunc (ULONG) Set to VSD_SET.

VSD_SETVOLUME Parameter - ulFlags

ulFlags (ULONG) Set to VSD_SETVOLUME.

VSD_SETVOLUME Parameter - pRequest

pRequest (PVSD_VOLUME_PARMS) Pointer to the 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 (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.

VSD_VOLUME_PARMS   vsdVol;
   vsdVol.ulVolume = pInstance->ulVolume;
   vsdVol.ulMasterAudio  = pInstance->ulMasterVolume;
   vsdVol.fMute = pInstance->fMute;
   vsdVol.ulVectoredVolume  = pInstance->ulTime;
   vsdVol.ulFlags  = VSD_VOLUME | VSD_MASTERVOLUME;


   lError = prInstance->pfnAUDIOIF((HVSD)prInstance->pMix->hvsd
                           VSD_SET,
                           VSD_SETVOLUME,
                           (PVOID)&vsdVol);

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