MMPM/2 Device Driver Reference:Data Types

MMPM/2 Device Driver Reference

Adding Support for Audio and Video Adapters Audio Physical Device Driver Template Audio Virtual Device Driver Template MAD16 PDD and VDD Sample Device Drivers PDD Sample for Video Capture Adapters PDD Sample for MPEG Video Playback Devices Audio Sample for Vendor-Specific Drivers Using the High-Resolution Timer Real-Time MIDI Subsystem Audio Device Driver Exerciser (PMADDE) Tool AP2/P2STRING Tool Ultimotion Data Stream Specification DDCMD Messages SHD Messages Vendor-Specific Driver Commands IOCtl Functions Data Types Types of MIDI Messages Notices Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation This section describes data types in the C language.

audio_update

This structure contains fields for the AUDIO_UPDATE IOCtl.

typedef struct _audio_update {
  CHAR           iobuf_type;      /*  Transmit or receive. */
  CHAR FAR      *buffer_address;  /*  Address of buffer be added. */
  ULONG          buffer_length;   /*  Length of buffer to be added. */
  USHORT         rc;              /*  Return code. */
  void FAR      *reserved;        /*  Reserved. */
} audio_update;

typedef struct audio_update FAR *UPDATE;

Fields

iobuf_type (CHAR):Transmit or receive iobuf. The defined values for this field are:

XMIT_IOBUF 0

REC_IOBUF 1

buffer_address (CHAR FAR *):Address of buffer be added.

buffer_length (ULONG):Length of buffer to be added.

rc (USHORT):Return code. The following values are defined for rc.

MAX_NUM_BUFFERS_REACHED	9
UPDATE_GENERAL_FAILURE	10
INVALID_BUFFER_LENGTH	11

reserved (void FAR *) Reserved.

BOOL

Boolean.

Valid values are:

• FALSE, which is 0
• TRUE, which is 1

typedef unsigned long BOOL;

BYTE

A byte.

typedef unsigned char BYTE;

CHAR

Single-byte character.

#define CHAR char

CONTROL_PARM

This data structure contains fields for the pParm and ulParmSize fields of the DDCMDCONTROL data structure.

typedef struct _CONTROL_PARM {
  ULONG     ulTime;  /*  Time in milliseconds. */
} CONTROL_PARM;

Fields

ulTime (ULONG) Specifies the time in milliseconds. The stream handler sets the cue time when the ulCmd field of the DDCMDCONTROL data structure is DDCMD_ENABLE_EVENT. The PDD returns the current time for DDCMD_STOP and DDCMD_PAUSE.

DDCMDCOMMON

This data structure contains common fields between all DDCMD data structures.

typedef struct _ddcmd_common_parm {
  ULONG       ulFunction;  /*  Function requested by stream handler. */
  HSTREAM     hStream;     /*  Data stream instance. */
} DDCMDCOMMON;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the data stream instance for this event.

DDCMDCONTROL0

This data structure contains fields for the DDCMD_CONTROL message.

typedef struct _ddcmd_control_parm {
  ULONG       ulFunction;  /* Function requested. */
  HSTREAM     hStream;     /* Stream handle. */
  HEVENT      hEvent;      /* Event handle. */
  ULONG       ulCmd;       /* Flags. */
  PVOID       pParm;       /* Pointer to CONTROL_PARM. */
  ULONG       ulParmSize;  /* See CONTROL_PARM. */
} DDCMDCONTROL;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event.

hEvent (HEVENT) Event handle.

ulCmd (ULONG) Defines the following flags:

DDCMD_START Starts a device.

DDCMD_STOP Stops a device and returns the current stream time in milliseconds. All buffers in the PDD are flushed and everything is reset to 0. The device driver sends the current stream time back to the stream handler in milliseconds (using the pParm and ulParmSize fields). For example, return a ULONG of stream time (in milliseconds) and the ULONG of 4 bytes is input in the ulParmSizefield.

DDCMD_PAUSE Pauses the device and returns the current stream time in milliseconds. Unlike DDCMD_STOP, DDCMD_PAUSE is not destructive. The device driver is able to resume its function at a later time, exactly where it was paused. DDCMD_ PAUSE returns the current stream time in milliseconds within the pParm field.

DDCMD_RESUME Resumes a currently paused stream. DDCMD_RESUME is only honored if the stream was paused previously. If the stream was stopped and the stream handler issues DDCMD_RESUME, an ERROR_INVALID_SEQUENCE is returned.

DDCMD_ENABLE_EVENT Enables event detection if your PDD supports events. The event message is sent to the device driver and reviews the structure. The hEvent field is a unique handle that signifies the event. pParm contains the stream time with which the event should be detected. This command would be honored whether currently in a streaming state, pause, or stop.

For example, a stream handler is programmed to be detected at 1000 milliseconds in the stream. It sends a DDCMD_ENABLE_EVENT to the device driver with a unique handle event (hEvent) and 1000 milliseconds stated in the pParm field. The device driver obtains the handle event, makes sure there are no duplicate entries, and adds the hEvent to a link list or array (depending on how the device driver is implemented). The device driver now knows it must report an event back to the stream handler when 1000 milliseconds has been reached in the stream. See SHD_REPORT_EVENT for further information.

DDCMD_DISABLE_EVENT Disables event detection in the device driver. An event handle is passed from the structure. The device driver searches its linked list or array to find the matching event handle and deletes it from the list.

DDCMD_PAUSE_TIME Pauses the time but not the stream.

DDCMD_RESUME_TIME Resumes the time.

pParm (PVOID) Pointer to the CONTROL_PARM data structure.

ulParmSize (ULONG) Size of the CONTROL_PARM data structure.

DDCMDDEREGISTER

This data structure contains fields for the DDCMD_DEREG_STREAM message.

typedef struct _ddcmd_deregister_parm {
  ULONG       ulFunction;  /*  Function requested by stream handler. */
  HSTREAM     hStream;     /*  Stream handle. */
} DDCMDDEREGISTER;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the stream handle needed at interrupt time.

DDCMDREADWRITE

This data structure contains fields for the DDCMD_READand DDCMD_WRITE messages.

typedef struct _ddcmd_readwrite_parm {
  ULONG       ulFunction;    /*  Function requested by stream handler. */
  HSTREAM     hStream;       /*  Stream handle. */
  PVOID       pBuffer;       /*  Buffer pointer. */
  ULONG       ulBufferSize;  /*  Buffer size. */
  PVOID       pProcessLin;   /*  Process linear record pointer. */
  BOOL        fEOS;          /*  Whether or not this is the EOS buffer. */
  ULONG       ulParm1;       /*  Reserved for future use. */
  ULONG       ulParm2;       /*  Reserved for future use. */
  ULONG       ulLength;      /*  Length of the structure. */
} DDCMDREADWRITE;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event.

pBuffer (PVOID) Buffer pointer of the empty buffer that the device driver fills from its record operation.

ulBufferSize (ULONG) Specifies the buffer size of the empty buffer.

pProcessLin (PVOID) Provides the 32-bit process linear address to a Ring 3 stream handler so the stream handler will have access to the buffers if a GDT or physical address is requested.

fEOS (BOOL) Whether or not this is the EOS buffer.

ulParm1 (ULONG) For MPEG, contains the initial audio system clock reference (SCR).

ulParm2 (ULONG) For MPEG, contains the Presentation Time Stamp (PTS).

ulLength (ULONG) Length of the structure.

DDCMDREGISTER

This data structure contains fields for the DDCMD_REG_STREAM message.

typedef struct _ddcmd_register_parm {
  ULONG       ulFunction;         /* Function requested by stream handler. */
  HSTREAM     hStream;            /* Stream handle. */
  ULONG       ulSysFileNum;       /* Device handle. */
  PSHDFN      pSHDEntryPoint;     /* Stream handler entry point. */
  ULONG       ulStreamOperation;  /* Stream operation. */
  SPCBKEY     spcbkey;            /* Input to the VSD or PDD (optional) buffer size. */
  ULONG       ulBufSize;          /* VSD or PDD output buffer size in bytes. */
  ULONG       ulNumBufs;          /* VSD or PDD output total number of buffers for SPCB. */
  ULONG       ulAddressType;      /* VSD or PDD output (required) addr ptr type to data buffer. */
  ULONG       ulBytesPerUnit;     /* VSD or PDD output (unused, set to zero). */
  MMTIME      mmtimePerUnit;      /* VSD or PDD output (Unused, set to zero). */
  E_DCB       dcbAudio;           /* Stream handler DCB. */
  HID         hid;                /* Stream handler ID. */
} DDCMDREGISTER;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the stream handle to communicate with the stream handler at interrupt time.

ulSysFileNum (ULONG) Specifies the device handle so the VSD or PDD can map the device instance to hStream. This field has to map with how the device has been initialized during AUDIO_INIT.

pSHDEntryPoint (PSHDFN) Specifies the stream handler entry point so that the device driver can call back into the stream handler during streaming time to report interrupts and events. For VSDs this is a user-level stream handler entry point.

ulStreamOperation (ULONG) Specifies the stream operation (record or playback). The device driver should verify with how it has been initialized through IOCtls. The following stream operations are defined (VSDs should verify with VSD_SET or VSD_OPEN settings):

STREAM_OPERATION_CONSUME Playback.

STREAM_OPERATION_PRODUCE Record.

spcbkey (SPCBKEY) Specifies input to the VSD or PDD (optional) buffer size.

ulBufSize (ULONG) Specifies VSD or PDD output buffer size in bytes that will be sent to the driver. The caller will fill in a default value. If the device driver does not override this value, it will be used to determine the buffer size.

Note: The device driver sets this field to indicate the buffer size that it would like to receive from the streaming subsystem. For MIDI, this field is usually set to 512. For DMA-based audio or other systems where the interrupt rate equals the buffer rate, this field should be set to about 1/30 the quantity of data consumed or produced per second. This field supplies the system with a minimal buffer size for wave audio. Because other system elements also negotiate to determine buffer size and for software motion video, the system might provide buffers smaller than the size requested.

ulNumBufs (ULONG) Specifies VSD or PDD output total number of buffers that will be allocated. The caller will fill in a default value. If the device driver does not override this value, it will be used to determine the total number of buffers.

ulAddressType(ULONG) Specifies VSD or PDD output (required) address pointer type to data buffer. The VSD or PDD tells the stream handler what type of address pointer it expects the data buffer to be. The stream handler then requests this address type to the SSM, so that the Sync/Stream Manager will send the correct type for each buffer request.

ADDRESS_TYPE_VIRTUAL	0
ADDRESS_TYPE_PHYSICAL	1
ADDRESS_TYPE_LINEAR	2

ulBytesPerUnit (ULONG) Specifies VSD or PDD output (unused, set to zero). Device driver timing.

mmtimePerUnit (MMTIME) Specifies VSD or PDD output. Device driver timing. (Unused, set to zero.)

dcbAudio (E_DCB) Specifies the input stream handler device control block ( DCB).

hid (HID) Specifies the input stream handler ID to be used for all communication with the stream handler.

DDCMDSETUP

This data structure contains fields for the DDCMD_SETUP message.

typedef struct _ddcmd_setup_parm {
  ULONG           ulFunction;       /* Function requested by stream handler. */
  HSTREAM         hStream;          /* Stream handle. */
  PSETUP_PARM     pSetupParm;       /* Pointer to SETUP_PARM. */
  ULONG           ulSetupParmSize;  /* Size of SETUP_PARM. */
} DDCMDSETUP;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event.

pSetupParm (PSETUP_PARM) Points to the SETUP_PARMdata structure.

ulSetupParmSize (ULONG) The size of the SETUP_PARMdata structure.

DDCMDSTATUS

This data structure contains fields for the DDCMD_STATUSmessage.

typedef struct _ddcmd_status_parm {
  ULONG            ulFunction;    /* Function requested by stream handler. */
  HSTREAM          hStream;       /* Stream handle. */
  PSTATUS_PARM     pStatus;       /* Pointer to STATUS_PARM. */
  ULONG            ulStatusSize;  /* Size or position time. */
} DDCMDSTATUS;

Fields

ulFunction (ULONG) Specifies the function requested by the stream handler.

hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event.

pStatus (PSTATUS_PARM) A pointer to the current position time as output. See STATUS_PARM.

ulStatusSize (ULONG) Specifies the size or position time as output.

E_DCB

This structure contains device-specific information. It is used at stream creation by the application media control device to deliver device-specific information to the source or target stream handlers.

typedef struct _E_DCB {
  ULONG     ulDCBLen;                 /* Length of structure. */
  SZ        szDevName[MAX_SPI_NAME];  /* Device driver name. */
  ULONG     ulSysFileNum;             /* File handle number. */
} E_DCB;

typedef E_DCB FAR * PE_DCB;

Fields

ulDCBLen (ULONG) Length of the device control block.

szDevName[MAX_SPI_NAME] (SZ) Identifies the device driver that the stream handler connects to for a particular stream instance. For stream handler device drivers, inter-device communication (IDC) is used to call the physical device driver. The device driver name must not be more than eight characters (excluding the file extension).

ulSysFileNum (ULONG) File handle number.

HEVENT

Event handle.

typedef ULONG HEVENT;

HID

Stream handler ID.

typedef ULONG HID;

HSTREAM

Stream handle.

typedef ULONG HSTREAM;

HVSD

VSD handle.

typedef PVOID HVSD;

HWND

Window handle.

typedef LHANDLE HWND;

LINECONNECTIONS

This structure contains data for the VSD_QUERYMIXCONNECTIONS and the VSD_SETMIXCONNECTIONS messages, and the MIX_GETCONNECTIONS and MIX_SETCONNECTIONS IOCtls.

typedef struct _LINECONNECTIONS {
  ULONG     ulLength;       /* Length of the structure. */
  ULONG     ulConnections;  /* Connection information. */
  ULONG     ulLine;         /* Line to get connections information for. */
} LINECONNECTIONS;

typedef LINECONNECTIONS FAR *PLINECONNECTIONS;

Fields

ulLength (ULONG) Length of the structure.

ulConnections (ULONG) Line(s) that ulLineis connected to.

Valid flags are:

• SINK_LINE_OUT Line out connection.
• SINK_SPEAKER Speaker connection.
• SINK_HEADPHONES Headphones connection.
• SINK_NULL Sink to nothing (remove all connections from this line).
• SINK_ALL Sink to everything.
• SINK_WAVE Wave connection.
• SINK_MIDI Midi connection.

ulLine (ULONG) Line to get connections information for.

The line described in ulLine field can have the following values:

• SOURCE_SYNTHESIZER Midi connection.
• SOURCE_LINE Line connection.
• SOURCE_INTERNAL_AUDIO Internal audio connection.
• SOURCE_MICROPHONE Microphone connection.
• SOURCE_WAVE Wave connection.
• SOURCE_PC_SPEAKER PC speaker connection.
• SOURCE_NULL Source is nothing (remove all connections to this line).
• SOURCE-MIDI Midi connection.

LONG

Signed integer in the range -2 147 483 648 through 2 147 483 647.

#define LONG long

Note

Where this data type represents a graphic coordinate in world or model space, its value is restricted to -134 217 728 through 134 217 727.

A graphic coordinate in device or screen coordinates is restricted to -32 768 through 32 767.

The value of a graphic coordinate may be further restricted by any transforms currently in force, including the positioning of the origin of the window on the screen. In particular, coordinates in world or model space must not generate coordinate values after transformation (that is, in device or screen space) outside the range -32 768 through 32 767.

MCI_AUDIO_BUFFER

This structure contains fields for the AUDIO_BUFFERfunction.

typedef struct _buffer {
  ULONG     ulFlags;         /* Indicates error condition. */
  ULONG     ulReadBufSize;   /* Data in Read queue. */
  ULONG     ulWriteBufSize;  /* Data in Write queue. */
  ULONG     ulReadBufTime;   /* Data in Read queue (in ms). */
  ULONG     ulWriteBufTime;  /* Data in Write queue (in ms). */
  ULONG     ulReadBufMax;    /* Max. data in Read queue. */
  ULONG     ulWriteBufMax;   /* Max. data in Write queue. */
  ULONG     ulPosition;      /* Position. */
  ULONG     ulPositionType;  /* Type of position units. */
  LONG      lReadBufCap;     /* Capacity of Read queue. */
  LONG      lWriteBufCap;    /* Capacity of Write queue. */
  LONG      lRequestBufCap;  /* Max. # of requests. */
} MCI_AUDIO_BUFFER;

typedef MCI_AUDIO_BUFFER FAR *LPMCI_AUDIO_BUFFER;

Fields

ulFlags (ULONG) Indicates an error condition occurred. The possible error states that can be flagged are:

AUDIO_UNDERRUN 1

AUDIO_OVERRUN 2

ulReadBufSize (ULONG) Amount of data in Read queue in bytes.

ulWriteBufSize (ULONG) Amount of data in Write queue in bytes.

ulReadBufTime (ULONG) Amount of data in Read queue in milliseconds.

ulWriteBufTime (ULONG) Amount of data in Write queue in milliseconds.

ulReadBufMax (ULONG) Maximum number of bytes ever in Read queue.

ulWriteBufMax (ULONG) Maximum number of bytes ever in Write queue.

ulPosition (ULONG) Time count since beginning of operation.

ulPositionType (ULONG) Specifies the type of position units. The defined values for this field are:

POS_MSECS       0    /* Position units in milliseconds since start */
MIDI_CLOCKS     1    /* Position units in # of MIDI clocks since start */
POS_BYTES       2    /* Position data in bytes                 */
SMPTE_24       24    /* Position corresponds with SMPTE 24 frames/sec */
SMPTE_25       25    /* Position corresponds with SMPTE 25 frames/sec */
SMPTE_30DF     29    /* Position corresponds with SMPTE 30 drop frame */
SMPTE_30       30    /* Position corresponds with SMPTE 30 frames/sec */

lReadBufCap (LONG) Capacity of Read queue; -1if variable.

lWriteBufCap (LONG) Capacity of Write queue; -1if variable.

lRequestBufCap (LONG) Maximum number of requests that can be queued.

MCI_AUDIO_CAPS

This structure contains fields for the AUDIO_CAPABILITYfunction.

typedef struct _MCI_AUDIO_CAPS {
  ULONG     ulLength;         /* Input. Structure length. */
  ULONG     ulSamplingRate;   /* Input/Output.  Sampling rate to query. */
  ULONG     ulChannels;       /* Input/Output.  Channels to query. */
  ULONG     ulBitsPerSample;  /* Input/Output.  Bits per sample to query. */
  ULONG     ulDataType;       /* Input/Output.  RIFF data type to query. */
  ULONG     ulOperation;      /* Input/Output.  OPERATION_PLAY or OPERATION_RECORD. */
  ULONG     ulSupport;        /* Output.  Boolean. */
  ULONG     ulDataSubType;    /* Output.  Data subtype to use. */
  ULONG     ulResourceUnits;  /* Output.  Resource units in this mode. */
  ULONG     ulResourceClass;  /* Output.  Resource class for this mode. */
  ULONG     ulBlockAlign;     /* Output.  Block alignment for this mode. */
  BOOL      fCanRecord;       /* Unused */
  ULONG     ulFlags;          /* Output.  Flags. */
  ULONG     ulCapability;     /* Output.  Capability of the device. */
} MCI_AUDIO_CAPS;

typedef MCI_AUDIO_CAPS FAR *PAUDIO_CAPS;

Fields

ulLength (ULONG) Input. Structure length.

ulSamplingRate (ULONG) Input/Output. Sampling rate to query.

ulChannels (ULONG) Input/Output. Channels to query.

ulBitsPerSample (ULONG) Input/Output. Bits per sample to query.

ulDataType (ULONG) Input/Output. RIFF data type to query. The definitions are in OS2MEDEF.H. A sample data type would be DATATYPE_WAVEFORM.

ulOperation (ULONG) Input/Output. OPERATION_PLAY or OPERATION_RECORD.

ulSupport (ULONG) Output. Boolean. Indicates if the device driver supports this mode.

Following are the valid return codes for ulSupport:

• SUPPORT_SUCCESS = Device supports this mode.
• UNSUPPORTED_RATE = Unsupported sampling rate.
• UNSUPPORTED_CHANNELS = Unsupported sampling rate.
• UNSUPPORTED_BPS = Unsupported bits per sample.
• UNSUPPORTED_DATATYPE = Unsupported data type.
• UNSUPPORTED_OPERATION = Unsupported operation.

ulDataSubType (ULONG) Output. Data subtype to use. Returned by device. The definitions are in OS2MEDEF.H.

ulResourceUnits (ULONG) Output. Data subtype to use. Returned by device.

ulResourceClass (ULONG) Output. Resource class for this mode. Returned by device.

ulBlockAlign (ULONG) Output. Block alignment for this mode. Returned by device.

fCanRecord (BOOL) Unused

ulFlags (ULONG) Output. Flags. Returned by device.

ulCapability (ULONG) Output. Capability of the device. Returned by device.

ulCapability can contain the following driver capabilities:

• SUPPORTED_MIX = Supports mixing capabilities.
• SUPPORTED_RIFF_MODES = Supports Riff data types on audio init.
• SUPPORTED_CAP = Supports capability IOCtls.

MCI_AUDIO_CHANGE

This structure contains fields for the AUDIO_STATUS function.

typedef struct _MCI_AUDIO_CHANGE {
  VOID FAR             *pvDevInfo;       /*  Pointer to information. */
  LONG                  lInput;          /*  Reserved. */
  LONG                  lOutput;         /*  Reserved. */
  LONG                  lMonitor;        /*  Record monitor level. */
  LONG                  lVolume;         /*  Volume setting. */
  LONG                  lVolumeDelay;    /*  Volume delay. */
  LONG                  lBalance;        /*  Balance setting. */
  LONG                  lBalanceDelay;   /*  Balance delay. */
  LONG                  lTreble;         /*  Treble tone-control setting. */
  LONG                  lBass;           /*  Base tone-control setting. */
  LONG                  lPitch;          /*  Pitch control setting. */
  MCI_AUDIO_DEVID       rInputList[8];   /*  Input list. */
  MCI_AUDIO_DEVID       rOutputList[8];  /*  Output list. */
  LPMCI_AUDIO_DEVID     prMoreInputs;    /*  Pointer to additional input. */
  LPMCI_AUDIO_DEVID     prMoreOutputs;   /*  Pointer to additional output. */
  LONG                  lGain;           /*  Gain control setting. */
  VOID FAR             *pvModeInfo;      /*  Pointer to mode-specific info. */
} MCI_AUDIO_CHANGE;

typedef MCI_AUDIO_CHANGE FAR *LPMCI_AUDIO_CHANGE;

Fields

pvDevInfo (VOID FAR *) Pointer to a data structure containing device- dependent information. For example, for the M-ACPA card, pvDevInfo points to a MCI_TRACK_INFO structure. This field is ignored if its value is NULL.

lInput (LONG) Reserved. Used in v0 for input select.

lOutput (LONG) Reserved. Used in v0 for output select.

lMonitor (LONG) Record monitor level.

lVolume (LONG) Volume setting; linear 0 min to 0x7FFFFFFF.

lVolumeDelay (LONG) Number of milliseconds over which change occurs.

lBalance (LONG) Balance setting 0 = left, 0x7FFFFFFF = right.

lBalanceDelay (LONG) Number of milliseconds over which change occurs.

lTreble (LONG) Treble tone-control setting.

lBass (LONG) Base tone-control setting.

lPitch (LONG) Pitch control setting.

rInputList[8] (MCI_AUDIO_DEVID) Input devices are specified using an array of MCI_AUDIO_DEVIDdata structures in the rInputList field. Unused entries are set to NULL_INPUT. The MCI_AUDIO_DEVID structure permits device specification by type and ordinal number (for those audio adapters that support more than one device of a specific type). For example, to specify stereo line input, set:

rInputList[0].ulDevType = STEREO_LINE_INPUT
rInputList[0].ulDevNum  = 1

rOutputList[8] (MCI_AUDIO_DEVID) Output devices are specified using an array of MCI_AUDIO_DEVID data structures in the rOutputList field. Unused entries are set to NULL_OUTPUT. The MCI_AUDIO_DEVID structure permits device specification by type and ordinal number (for those audio adapters that support more than one device of a specific type). For example, to specify stereo line output, set:

rOutputList[0].ulDevType = STEREO_LINE_OUTPUT
rOutputList[0].ulDevNum  = DEVICE_1.

prMoreInputs (LPMCI_AUDIO_DEVID) Pointer to additional input device IDs.

prMoreOutputs (LPMCI_AUDIO_DEVID) Pointer to additional output device IDs.

lGain (LONG) Input (record) gain-control setting.

pvModeInfo (VOID FAR *) Pointer to a mode-specific data structure. For MIDI, this points to a MIDI_INFO structure.

MCI_AUDIO_CONTROL

This structure contains fields for the AUDIO_CONTROL function.

typedef struct _MCI_AUDIO_CONTROL {
  USHORT     usIOCtlRequest;
  VOID      *pbRequestInfo;
  ULONG      ulPosition;
  SHORT      sReturnCode;
} MCI_AUDIO_CONTROL;

typedef MCI_AUDIO_CONTROL FAR *LPMCI_AUDIO_CONTROL

Fields

usIOCtlRequest (USHORT) IOCtl request to be executed. The defined values for this field are:

AUDIO_CHANGE (0) Enables an application to change adapter characteristics. It is issued while the audio device is open. The characteristics contained in the MCI_AUDIO_CHANGE structure such as input source can be changed by this request.

Note: AUDIO_CHANGE requests have the potential to break the data flow. Some audio devices might require that input, output, and monitor selections be performed prior to starting a change operation.

To change an adapter's characteristics, the desired values should be placed in the respective fields and the request issued. Notice that all possible combinations of these fields are not necessarily supported by the device driver. Invalid combinations result in an error returned by AUDIO_CHANGE.

The effects of issuing this request can vary for each requested change. If a given field is to remain unchanged, set that field to AUDIO_IGNORE (-1).

AUDIO_START (1) Initiates the flow of audio data to or from the adapter. It also causes the internal position and timing values to be set to the value contained in ulPosition. Therefore, an immediate call to AUDIO_BUFFER returns a position value equal to the ulPosition value specified in AUDIO_ START. The audio device must be opened and initialized (through OPEN and AUDIO_INIT requests) before calling AUDIO_START. Otherwise, an error is returned.

There is no pbRequestInfo field for AUDIO_START.

AUDIO_STOP (2) Stops the current activity in progress on the audio device. For example, if the device was recording, the recording activity would be stopped. This operation does not change the current configuration (such as sampling rate, input source, and so forth) of the device; it simply terminates the current operation. Consequently, it also stops data flow between the device driver and the application. Any data left in the buffers is discarded. Notice that the Write buffers can be drained using the AUDIO_WAIT request. Use the AUDIO_PAUSE operation instead of AUDIO_STOP if the operation must be resumed at the point it left off.

The ulPositionvalue is used to specify when the stop is to occur. A value of less than the current position or 0results in an immediate execution of the stop.

There is no pbRequestInfofield for AUDIO_STOP.

AUDIO_PAUSE (3) Used to suspend all data flow between the application and the adapter. This request does not flush the kernel buffers or the adapter buffers. Data flow can be resumed by using AUDIO_RESUME. If recording, data is lost during the time that the device driver is paused.

The pbRequestInfovalue is used to specify when the pause is to occur. A value of less than the current position results in an immediate pause.

There is no pbRequestInfofield for AUDIO_PAUSE.

AUDIO_RESUME (4) Used to resume the flow of data that was suspended by AUDIO_PAUSE. Notice that an ulPositionvalue of non-zero is not currently defined and should not be used.

There is no pbRequestInfofield for AUDIO_RESUME.

pbRequestInfo Pointer to a structure that contains information specific to each type of IOCtl request. See the IOCtl request descriptions above for specifics on what pbRequestInfo points to for each request. Notice that these requests are executed at a point in time specified by the caller.

ulPosition (ULONG) Number of units before the request should be executed. This value is used to specify cue points. Caller requests are executed ulPosition number of units from the beginning of the first Write operation after opening a track. Depending on the DSP code loaded and the current mode of operation, units can be bytes, time, or some other unit of measure. For example, to increase the volume of a track after the first 1,000 milliseconds of data have been written to the adapter, issue an AUDIO_ CHANGE request with ulPosition set to 1000. This example assumes that the track information pointed to by :pbRequestInfo has been initialized appropriately, and that MCI_AUDIO_BUFFER.ulPositionType = POS_MSECS.

If a request is made for a position number that has already occurred, it is processed immediately. Requests with a position number of 0are also processed immediately.

sReturnCode (SHORT) Used to return any error code. The defined values for this field are:

AC_UNINITED	1	/* Device must be initialized or loaded first */
FULL_QUEUE	2	/* Max. number of requests exceeded */
AC_UNPAUSED	3	/* Resume issued, but device not paused */
INVALID_REQUEST	4	/* Bad MCI_AUDIO_CONTROL.usIOCtlRequest */
AC_UNSTARTED	5	/* Device must be started first */
INVALID_INPUT_LIST	7	/* Device in MCI_AUDIO_CHANGE.input_list is not supported */
INVALID_OUTPUT_LIST	8	/* Device in MCI_AUDIO_CHANGE.output_list is not supported */

MCI_AUDIO_DEVID

typedef struct _MCI_AUDIO_DEVID {
  ULONG     ulDevType;
  ULONG     ulDevNum;
} MCI_AUDIO_DEVID;

typedef MCI_AUDIO_DEVID FAR *LPMCI_AUDIO_DEVID;

Fields

ulDevType (ULONG) Defined values for ulDevTypeare shown for input and output devices:

/* Input Devices */
#define  NULL_INPUT                   0
#define  STEREO_LINE_INPUT            1
#define  LEFT_LINE_INPUT              2
#define  RIGHT_LINE_INPUT             3
#define  MIC_INPUT                    4
#define  BOOSTED_MIC_INPUT            5
#define  PHONE_LINE_INPUT             6
#define  HANDSET_INPUT                7
#define  SYNTH_INPUT                  8
#define  DIGITAL_PHONE_LINE_INPUT     9
#define  DIGITAL_HANDSET_INPUT       10
#define  MIDI_IN_PORT                11
#define  LOOPBACK                    12
#define  DEFAULT_INPUT               0xFFFFFFFF
/* Values between 0x20000000 and 0xFFFFFFFE are reserved */

/* Output Devices */
#define  NULL_OUTPUT                  0
#define  STEREO_LINE_OUTPUT           1
#define  LEFT_LINE_OUTPUT             2
#define  RIGHT_LINE_OUTPUT            3
#define  SPEAKER_OUTPUT               4
#define  HEADPHONES_OUTPUT            5
#define  PHONE_LINE_OUTPUT            6
#define  HANDSET_OUTPUT               7
#define  SYNTH_OUTPUT                 8
#define  DIGITAL_PHONE_LINE_OUTPUT    9
#define  DIGITAL_HANDSET_OUTPUT      10
#define  MIDI_OUT_PORT               11
#define  DEFAULT_OUTPUT              0xFFFFFFFF
/* Values between 0x20000000 and 0xFFFFFFFE are reserved */

ulDevNum (ULONG) The defined values for ulDevNum are:

#define  DEFAULT_DEVICE               0
#define  DEVICE_1                     1
#define  DEVICE_2                     2

MCI_AUDIO_HPI

This structure contains fields for the AUDIO_HPI function.

typedef struct _hpi {
  VOID FAR                *pvEntry ();     /*  Pointer to direct-call entry point. */
  VOID FAR                *pvCallBack ();  /*  Pointer to callback routine. */
  LPMCI_AUDIO_IOBUFFER     prXBuff;        /*  Pointer to new Transmit buffer. */
  LPMCI_AUDIO_IOBUFFER     prRBuff;        /*  Pointer to new Receive buffer. */
  USHORT                   usFlags;        /*  Reserved. */
} MCI_AUDIO_HPI;

typedef MCI_AUDIO_HPI FAR *LPMCI_AUDIO_HPI;

Fields

pvEntry () (VOID FAR *) Pointer to the direct-call entry point. The direct call interface is defined below.

void (far *iobuf.ep)(short funcid, void far *data, short len);

/* Definitions for funcid */

EP_OPEN       0
EP_CLOSE      1
EP_READ       2
EP_WRITE      3
EP_INIT       4
EP_STATUS     5
EP_CONTROL    6
EP_BUFFER     7
EP_LOAD       8
EP_WAIT       9
EP_HPI       10
EP_UPDATE    11
/* On return, AX contains an error code, or 0 if successful */

pvCallBack () (VOID FAR *) Pointer to the callback routine. The application passes the address of a callback routine (under DOS) or system semaphore handle (under OS/2) in pvCallBack (). Notice that the DOS callback routine must be an interrupt routine, that is, it must return with an IRET, not a RET instruction. Care must be taken not to re-enter DOS. For example, the interrupt can occur while executing a DOS call. Any call to DOS made in the callback routine will result in DOS being entered a second time and will probably cause a system halt.

If not NULL, the address is called (under DOS) or the semaphore is cleared (under OS/2) based on the state of the CBDATA, CBBLOCK, CBIOBUF, and CBERROR flags in usRunFlags:

CBDATA The address is called (under DOS) or the semaphore is cleared (under OS/2) for each data byte sent to, or received from, the device. Notice that some devices transfer data to and from the host only in blocks, in which case this bit has the same effect as CBBLOCK.

CBBLOCK The address is called or the semaphore is cleared for each complete block of data sent to, or received from, the device.

CBIOBUF The address is called or the semaphore is cleared each time the entire contents of IOBUF are sent to, or received from, the device.

CBERROR The address is called or the semaphore is cleared each time a device error is detected by the device.

CBUNDERRUN The address is called or the semaphore is cleared each time an underrun or overrun is detected by the device.

This process will continue until either the device is stopped (or closed) or the AUDIO_HPI function is called again with pvCallBack ()set to NULL. The device interrupt rate generally corresponds with the position resolution returned in lResolutionof the MCI_AUDIO_INIT structure.

prXBuff (LPMCI_AUDIO_IOBUFFER) Pointer to new Transmit buffer to use. Set prXBuff to NULL to use the default internal buffers.

prRBuff (LPMCI_AUDIO_IOBUFFER) Pointer to new Receive buffer to use. Set prRBuff to NULL to use the default internal buffers.

By default, the internal buffer sizes are usually 512 bytes. Any buffers provided must be an even number of bytes in length.

usFlags (USHORT) Reserved.

MCI_AUDIO_INIT

This structure contains fields for the AUDIO_INITfunction.

typedef struct _init {
  LONG           lSRate;                 /*  Sampling rate. */
  LONG           lBitsPerSRate;          /*  # of bits per sample. */
  LONG           lBsize;                 /*  Block size. */
  SHORT          sMode;                  /*  Audio mode. */
  SHORT          sChannels;              /*  Number of audio channels. */
  LONG           lResolution;            /*  Resolution of position data. */
  CHAR           abLoadPath[LOAD_PATH];  /*  Path of DSP code to load. */
  ULONG          ulFlags;                /*  Fixed, signed, and so on. */
  ULONG          ulOperation;            /*  Desired operation. */
  SHORT          sReturnCode;            /*  Return code for operation. */
  SHORT          sSlotNumber;            /*  Slot number of adapter. */
  SHORT          sDeviceID;              /*  Adapter type ID. */
  VOID FAR      *pvReserved;             /*  Reserved field. */
  ULONG          ulVersionLevel;         /*  Version level of device driver. */
} MCI_AUDIO_INIT;

typedef MCI_AUDIO_INIT FAR *LPMCI_AUDIO_INIT;

Fields

lSRate (LONG) Indicates the sampling rate in Hz, if applicable.

lBitsPerSRate (LONG) Indicates the number of bits per sample, if applicable.

lBsize (LONG) Indicates the data block size for blocked data. Some devices perform I/O in fixed block amounts. For these devices, a full block of data must be written to the device driver before it is written to the device (during playback). During Record operations, a full block of data must be received before it becomes available to the application. The lBsize field should be less than or equal to 1024 bytes, however, it cannot be guaranteed not to exceed that size.

sMode (SHORT) Indicates the general audio mode, for example, PCM, ADPCM, or MIDI. The defined values for sMode are:

ADPCM              1         /* AVC type ADPCM                */
PCM                2         /* PCM                           */
MU_LAW             3         /* Mu-law                        */
MIDI               4         /* MIDI                          */
A_LAW              5         /* A-law                         */
SOURCE_MIX         6         /* External analog audio source  */
SPV2               7         /* Reserved (Speech Viewer/2)    */
ADPCMXA            8         /* XA CD ROM                     */
DSSM               9         /* DS201 Standard mode           */
DSMM              10         /* DS201 Movie mode              */
CVSD              11         /* CVSD                          */
SPV2BCPCM         25         /* Reserved (Speech Viewer/2)    */
SPV2PCM           26         /* Reserved (Speech Viewer/2)    */
SPV2NONE          27         /* Reserved (Speech Viewer/2)    */
IDLE             999         /* Deinitialize the track        */
CLAIM_HDWR     32000         /* Claim hardware for other use  */

sChannels (SHORT) Indicates the number of audio channels, for example, mono is 1, stereo is 2.

lResolution (LONG) Set to indicate the resolution of position data returned by the device driver. For example, the M-ACPA device driver can return position data rounded to the nearest 100 milliseconds when playing AVC ADPCM (.1-second blocked) data.

abLoadPath[LOAD_PATH] (CHAR) If the digital signal processor (DSP) code must be loaded before the operation can be performed, the device driver sets the LOAD_CODE bit in ulFlags. In this case, the name of the DSP file to be loaded is specified in the abLoadPath field. Notice that the application must call AUDIO_LOAD before trying to perform Read or Write operations.

Keep a single copy of each DSP load module maintained and grouped together in a single subdirectory. This subdirectory can be referenced in the DOS APPEND command or the OS/2 DPATH CONFIG.SYS statement.

The maximum path length available for DSP code modules in abLoadPath is:

LOAD_PATH    260    /* DOS and OS/2 length is 260 */

ulFlags (ULONG) A bit flag indicating several pieces of information. The defined values for ulFlags are:

• FIXED (0x00000001l) Specify that the data is fixed, as opposed to variable rate or size.
• LEFT_ALIGNED (0x00000002l) Specify that the data is left aligned on a byte boundary. This field is applicable only if lBitsPerSRateis not a multiple of 8.
• RIGHT_ALIGNED (0x00000004l) Specify that the data is right aligned on a byte boundary. This bit is applicable only if lBitsPerSRateis not a multiple of 8.
• TWOS_COMPLEMENT (0x00000008l) Specify that the data is represented by using TWOS_COMPLEMENT signed format. If this bit and the SIGNED bit are both 0, the data is in unsigned format.
• SIGNED (0x00000010l) Specify that the data is represented using signed magnitude format, whereby the highest bit is set to 1to indicate a negative value, and the lower bits specify the absolute value. If this bit and the TWOS_COMPLEMENT bit are both 0, the data is in unsigned format.
• BIG_ENDIAN (0x00000020l) Specifies that the most significant bytes precede the least significant bytes. This bit is applicable only if lBitsPerSRateis greater than 8(multibyte values).
• RIFF_DATATYPE (0x00000040l) sMode contains a RIFF datatype.
• PITCH (0x00100000l) Specifies that pitch control is supported.
• INPUT (0x00200000l) Specifies that input select is supported.
• OUTPUT (0x00400000l) Specifies that output select is supported.
• MONITOR (0x00800000l) Specifies that monitor select is supported.
• VOLUME (0x01000000l) Specifies that volume select is supported.
• VOLUME_DELAY (0x02000000l) Specifies that volume delay is supported.
• BALANCE (0x04000000l) Specifies that balance control is supported.
• BALANCE_DELAY (0x08000000l) Specifies that balance delay is supported.
• TREBLE (0x10000000l) Specifies that treble control is supported
• BASS (0x20000000l) Specifies that bass control is supported.
• BESTFIT_PROVIDED (0x40000000l) Indicates that the best fit is returned.
• LOAD_CODE (0x80000000l) Indicates that a DSP load is needed.

ulOperation (ULONG) Specifies the desired operation. The defined values for this field are:

OPERATION_PLAY     0x80000001
OPERATION_RECORD   0x80000002
PLAY_AND_RECORD    0x80000003
ANALYSIS           0x80000006      /* Speech Viewer/2 */
DISTANCE           0x80000007      /* Speech Viewer/2 */
MIGRATION          0x80000008      /* Speech Viewer/2 */

Notice that the high-order bit is set in all cases.

sReturnCode (SHORT) Return code for the operation. The defined values for sReturnCode are:

NO_PLAY              1    /* Cannot play                       */
NO_RECORD            2    /* Cannot record                     */
NO_RECORD_AND_PLAY   3    /* Cannot both play and record       */
INVALID_REQUEST      4    /* Request was not valid             */
CONFLICT             5    /* Conflicting information was found */
OVERLOADED           6    /* Out of DSP MIPS or Memory         */
DOWNLEVEL_DD         7    /* DD is an earlier version than
                             the version requested by the
                             application                       */
DSP_LOAD_PENDING_ON_OTHER_TRK  8  /* Other track hasn't loaded DSP  */

sSlotNumber (SHORT) If the call is successful, the slot number of the device is returned in the sSlotNumber field.

sDeviceID (SHORT) If the call is successful, the type of device is returned in the sDeviceID field. The defined values used by sDeviceID are:

MINIDD               0    /* Minimal device driver             */
ACPA                 1    /* IBM ACPA                          */
MACPA                2    /* IBM M-ACPA                        */
MPU401               3    /* Roland MPU-401 or compatible      */
SOUND_BLASTER        4    /* Creative Labs Sound Blaster       */
IMF                  5    /* IBM Music Feature                 */
PS1                  6    /* IBM Personal System/1 audio
                             feature                           */
PAS16                7    /* Media Vision ProAudio Spectrum 16 */
DS201                9    /* DS201 audio adapter               */

pvReserved (VOID FAR *) The caller must fill this field in with a ulSysFileNumber.

ulVersionLevel (ULONG) Specifies the audio device driver version. As audio device drivers evolve, some changes are sure to occur. The ulVersionLevel field is used to allow new functions to be added to audio device drivers without losing compatibility with existing applications.

When an application calls AUDIO_INIT, it specifies the version level of the requested device driver. The audio device driver compares its version level with that passed by the application and ensures that they are compatible. If the device driver is an earlier version than that required by the application, it returns an error. If the version level of the device driver is newer than the application, the driver ensures that calls from the application are handled in a manner consistent with the version level of the application.

The value specified in ulVersionLevel is the binary-coded decimal representation of the version and build level. For example, Version 1.0 Build 15 is coded 0x01000015. The high-order byte is the version, the next byte is the revision number, and the least significant two bytes are the build number.

MCI_AUDIO_IOBUFFER

This structure contains fields for the AUDIO_HPI function.

typedef struct _MCI_AUDIO_IOBUFFER {
  LONG           lSize;       /*  Size of data buffers. */
  CHAR FAR      *pHead;       /*  Queue head pointer. */
  CHAR FAR      *pTail;       /*  Queue tail pointer. */
  LONG           lCount;      /*  # of bytes queued. */
  ULONG          ulPosition;  /*  Position counter. */
  LONG           lDelay;      /*  # of units before next I/O. */
  USHORT         usRunFlags;  /*  Start/stop/pause bits. */
  USHORT         usSelInc;
  CHAR FAR      *pBuffer;     /*  Array of pointers. */
} MCI_AUDIO_IOBUFFER;

typedef MCI_AUDIO_IOBUFFER FAR *LPMCI_AUDIO_IOBUFFER;

Fields

lSize (LONG) Total size in bytes of the data buffers.

pHead (CHAR FAR *) Queue head pointer (data added here).

pTail (CHAR FAR *) Queue tail pointer (data removed here)

lCount (LONG) Total number of data bytes currently queued.

ulPosition (ULONG) Position counter.

lDelay (LONG) Number of pos units before the next I/O.

usRunFlags (USHORT) Start/stop/pause bits.

usSelInc (USHORT)

pBuffer (CHAR FAR *) Array of pointers describing buffers.

MCI_AUDIO_LOAD

This structure contains fields for the AUDIO_LOAD function.

typedef struct _load {
  CHAR FAR      *pbBuffer;  /*  Pointer to buffer. */
  ULONG          ulSize;    /*  Size of DSP code (in bytes). */
  ULONG          ulFlags;   /*  Indicates start or end of operation. */
} MCI_AUDIO_LOAD;

typedef MCI_AUDIO_LOAD FAR *LPMCI_AUDIO_LOAD;

Fields

pbBuffer (CHAR FAR *) Pointer to buffer containing DSP code.

ulSize (ULONG) Size of DSP code (in bytes).

ulFlags (ULONG) Indicates start or end of operation. The defined values for this field are:

LOAD_START    1    /* Indicates that this is the first block  */
LOAD_END      2    /* Indicates that this is the last block   */
LOAD_32BIT   10

MCI_AUDIO_STATUS

This structure contains fields for the AUDIO_STATUS function.

typedef struct _stat {
  LONG                 lSRate;         /*  Sampling rate. */
  LONG                 lBitsPerSRate;  /*  # of bits per sample. */
  LONG                 lBsize;         /*  Block size. */
  SHORT                sMode;          /*  Mode. */
  SHORT                sChannels;      /*  # of channels. */
  ULONG                ulFlags;        /*  Flags. */
  ULONG                ulOperation;    /*  Operation. */
  MCI_AUDIO_CHANGE     rAudioChange;   /*  MCI_AUDIO_CHANGE structure. */
} MCI_AUDIO_STATUS;

typedef MCI_AUDIO_STATUS FAR *LPMCI_AUDIO_STATUS;

Fields

lSRate (LONG) Indicates the sampling rate in Hz (if applicable).

lBitsPerSRate (LONG) Indicates the number of bits per sample (if applicable ).

lBsize (LONG) Indicates the data block size for blocked data.

sMode (SHORT) Indicates the general audio mode, for example, PCM, ADPCM, or MIDI. The possible values are listed under the sModefield of MCI_AUDIO_INIT.

sChannels (SHORT) Indicates the number of audio channels, for example, mono is 1, stereo is 2.

ulFlags (ULONG) A bit flag. The possible values are listed under the ulFlags field of MCI_AUDIO_INIT.

ulOperation (ULONG) Specifies the desired operation. The defined values for this field are:

STOPPED	0x80000000
PLAYING	0x80000001
RECORDING	0x80000002
PLAYING_AND_RECORDING	0x80000003
UNINITIALIZED	0xFFFFFFFF

Notice that the value associated with the current operation is returned in the ulOperation field.

rAudioChange (MCI_AUDIO_CHANGE) An MCI_AUDIO_CHANGE data structure.

MCI_DEVICESETTINGS_PARMS

This structure contains fields for the MCI_DEVICESETTINGS message.

typedef struct _MCI_DEVICESETTINGS_PARMS {
  HWND       hwndCallback;   /*  Window handle. */
  HWND       hwndNotebook;   /*  Handle to notebook window. */
  USHORT     usDeviceType;   /*  Device type. */
  PSZ        pszDeviceName;  /*  Logical device name. */
} MCI_DEVICESETTINGS_PARMS;

typedef MCI_DEVICESETTINGS_PARMS *PMCI_DEVICESETTINGS_PARMS;

Fields

hwndCallback (HWND) A window handle to be used in returning asynchronous notification messages. This parameter must be specified if the MCI_NOTIFY flag is specified.

hwndNotebook (HWND) Handle to notebook window.

usDeviceType (USHORT) Device type.

pszDeviceName (PSZ) Logical device name.

MCI_TRACK_INFO

typedef struct _info {
  USHORT     usMasterVolume;       /*  Master volume control. */
  USHORT     usDitherPct;          /*  Dither percent control. */
  USHORT     usMasterVolumeDelay;  /*  Master volume delay. */
  USHORT     usMasterBalance;      /*  Master balance control. */
} MCI_TRACK_INFO;

typedef MCI_TRACK_INFO FAR *LPMCI_TRACK_INFO;

Fields

usMasterVolume (USHORT) Master volume control.

usDitherPct (USHORT) Dither percent control.

usMasterVolumeDelay (USHORT) Master volume delay.

usMasterBalance (USHORT) Master balance control.

MIDI_INFO

This structure contains MIDI-mode information.

typedef struct _mode_info {
  SHORT     sTempo;         /*  Tempo. */
  SHORT     sCPQN;          /*  Timing. */
  SHORT     sMidiSwitches;  /*  Common MIDI switches. */
  SHORT     sReserved[5];   /*  Reserved field. */
} MIDI_INFO;

Fields

sTempo (SHORT) Tempo in 1/10 beats per minute (nominally 120).

sCPQN (SHORT) Timing clocks per quarter note (nominally 96).

sMidiSwitches (SHORT) The following MIDI switches are defined:

MIDI_THRU_OUT  1         /* Configure MIDI-Thru connector   as MIDI-Out */
MIDI_THRU_THRU 0         /* Configure MIDI-Thru connector  as MIDI-Thru */

sReserved[5] (SHORT) Reserved field.

MIXERCONTROL

This structure contains fields for the VSD_QUERYMIXCONTROL and the VSD_ SETMIXCONTROL messages and the MIX_GETCONTROL and MIX_SETCONTROL IOCtls.

typedef struct _MIXERCONTROL {
  ULONG     ulLength;   /*  Length of the structure. */
  ULONG     ulLine;     /*  Line to control. */
  ULONG     ulControl;  /*  Input. Mixer attribute to control. */
  ULONG     ulSetting;  /*  Setting for mixer attribute. */
} MIXERCONTROL;

typedef MIXERCONTROL FAR *PMIXERCONTROL; 

Fields

ulLength (ULONG) Length of the structure.

ulLine (ULONG) Line to control. This field can contain the following sources or sinks:

• SOURCE_SYNTHESIZER :Midi connection.
• SOURCE_MIXER :Source mixer connection.
• SOURCE_LINE :Line connection.
• SOURCE_INTERNAL_AUDIO :Internal audio connection.
• SOURCE_MICROPHONE :Microphone connection.
• SOURCE_WAVE :Wave connection.
• SOURCE_PC_SPEAKER :PC speaker connection.
• SINK_LINE_OUT :Line out connection.
• SINK_SPEAKER :Speaker connection.
• SINK_HEADPHONES :Headphones connection.
• SINK_GENERIC :Generic connection.
• SINK_NULL :Null connection.

ulControl (ULONG) Attribute to modify line. This field can contain:

• MIX_BALANCE :Separate balance control.
• MIX_ALC :Auto level control.
• MIX_MONITOR :Monitor control.
• MIX_CROSSOVER :Crossover change.
• MIX_LOUDNESS :Loudness equalization.
• MIX_MUTE :Channel mute.
• MIX_REVERB :Reverb.
• MIX_STEREOENHANCE :Stereo enhance.
• MIX_CUSTOM1 :Custom effect #1.
• MIX_CUSTOM2 :Custom effect #2.
• MIX_CUSTOM3 :Custom effect #3.
• MIX_BASS :Bass.
• MIX_TREBLE :Treble.
• MIX_PITCH :Pitch modifications.
• MIX_CHORUS :Chorus.
• MIX_VOLUME :Volume controls.

ulSetting (ULONG) Setting for mixer attribute.

For VSD_QUERYMIXCONTROL and VSD_SETMIXCONTROL messages, the ulSetting field can range from 0 to 100.

For MIX_GETCONTROL and MIX_SETCONTROL IOCtls, the ulSetting field can range from 0 to 0x7FFFFFFF. A value of 0xFFFFFFFF is invalid and should be ignored.

MIXERLINEINFO

This structure contains fields for the VSD_QUERYMIXLINE message and the MIX_GETLINEINFO IOCtl.

typedef struct _MIXERLINEINFO {
  ULONG     ulLength;               /*  Input. Length of the structure. */
  ULONG     ulNumChannels;          /*  Output. Number of channels. */
  ULONG     ulSupport;              /*  Output. Supported mixer attributes. */
  ULONG     ulConnectionsPossible;  /*  Output. Possible connections. */
  ULONG     ulLine;                 /*  Input. The line to query. */
} MIXERLINEINFO;

typedef MIXERLINEINFO FAR *PMIXERLINEINFO;

Fields

ulLength (ULONG) Length of the structure.

ulNumChannels (ULONG) Number of channels.

ulSupport (ULONG) Supported mixer attributes. The following values are defined for ulSupport:

• MIX_BALANCE :Separate balance control.
• MIX_ALC :Auto level control.
• MIX_MONITOR :Monitor control.
• MIX_CROSSOVER :Crossover change.
• MIX_LOUDNESS :Loudness equalization.
• MIX_MUTE :Channel mute.
• MIX_REVERB :Reverb.
• MIX_STEREOENHANCE :Stereo enhance.
• MIX_CUSTOM1 :Custom effect #1.
• MIX_CUSTOM2 :Custom effect #2.
• MIX_CUSTOM3 :Custom effect #3.
• MIX_BASS :Bass.
• MIX_TREBLE :Treble.
• MIX_PITCH :Pitch modifications.
• MIX_CHORUS :Chorus.
• MIX_VOLUME :Volume controls.

ulConnectionsPossible (ULONG) Lines ulLine can connect to.

ulLine (ULONG) Line to set or query information.

The ulLinefield must be filled in by the caller with one of the following VSD lines:

• SOURCE_SYNTHESIZER :Midi connection.
• SOURCE_MIXER :Mixer connection.
• SOURCE_LINE :Line connection.
• SOURCE_INTERNAL_AUDIO :Internal audio connection.
• SOURCE_MICROPHONE :Microphone connection.
• SOURCE_WAVE :Wave connection.
• SOURCE_PC_SPEAKER :PC speaker connection.

MMTIME

Universal Chinatown time (1/3000 second).

typedef ULONG MMTIME;

MSG_REPORTEVENT

This structure contains fields for the SHC_REPORT_EVENT message (passed with SpiSendMsg).

typedef struct _MSG_REPORTEVENT {
  ULONG      ulMsgLen;      /*  Length of structure. */
  HEVENT     hevent;        /*  Event handle. */
  ULONG      ulStreamTime;  /*  Time in milliseconds of stream position. */
} MSG_REPORTEVENT;

typedef MSG_REPORTEVENT FAR *PMSG_REPORTEVENT;

Fields

ulMsgLen (ULONG) Length of structure.

hevent (HEVENT) Event handle passed back to stream handler.

ulStreamTime (ULONG) Time in milliseconds of stream position.

MSG_REPORTINT

This structure contains fields for the SHC_REPORT_INT message (passed with SpiSendMsg).

typedef struct _MSG_REPORTINT {
  ULONG     ulMsgLen;      /*  Length of structure. */
  PVOID     pBuffer;       /*  Return pointer. */
  ULONG     ulFlag;        /*  Reason for interrupt. */
  ULONG     ulStatus;      /*  Bytes read or written. */
  ULONG     ulStreamTime;  /*  Stream time in milliseconds. */
} MSG_REPORTINT;

typedef MSG_REPORTINT FAR *PMSG_REPORTINT;

Fields

ulMsgLen (ULONG) Length of structure.

pBuffer (PVOID) Pointer to buffer being returned (or null for no buffer to return).

ulFlag (ULONG) Specifies the reason for the interrupt. This field defines the following flags:

• ERROR
• STREAM_STOP_NOW
• SHD_READ_COMPLETE*
• SHD_WRITE_COMPLETE

Note:

1. ERROR must be ORed with SHD_READ_COMPLETE or SHD_WRITE_COMPLETE.
2. Do not set SHD_READ_COMPLETE or SHD_WRITE_COMPLETE if not returning a buffer.

ulStatus (ULONG) Return code or bytes read or written.

ulStreamTime (ULONG) Stream time in milliseconds.

PFN

Pointer to a procedure.

typedef _PFN *PFN;

In the header file, this is a two-part definition as shown below:

typedef  int   (APIENTRY _PFN) ();
typedef  _PFN  *PFN;

PSHDFN

Pointer to a function prototype for a stream handler device entry routine.

typedef ULONG (FAR *PSHDFN) (PVOID pParmIn);

In the header file, this is a two-part defintion as shown below:

typedef ULONG (FAR *PSHDFN) (PVOID pParmIn);
typedef PVOID PSHDFN;

PSZ

Pointer to a null-terminated string.

If you are using C++ **, you may need to use PCSZ.

typedef unsigned char *PSZ;

SETUP_PARM

This data structure contains fields for the pSetupParmand ulSetupParmSizefields of the DDCMDSETUP data structure.

typedef struct _SETUP_PARM {
  ULONG     ulStreamTime;  /*  Stream time in milliseconds. */
  ULONG     ulFlags;       /*  Flags (input/output). */
} SETUP_PARM;

Fields

ulStreamTime (ULONG) Specifies the stream time in milliseconds.

ulFlags (ULONG) Device drivers should ignore this field.

SHD_COMMON

This data structure contains common fields between all SHD data structures.

typedef struct _shd_common_parm {
  ULONG       ulFunction;  /*  Function requested by PDD. */
  HSTREAM     hStream;     /*  Stream handle. */
} SHD_COMMON;

typedef SHD_COMMON *PSHD_COMMON;

Fields

ulFunction (ULONG) Specifies the function requested by the PDD.

hStream (HSTREAM) Specifies the stream handle needed at interrupt time.

SHD_REPORTEVENT

This data structure contains fields for the SHD_REPORT_EVENT message.

typedef struct _shd_reportevent_parm {
  ULONG       ulFunction;    /*  Function requested by PDD. */
  HSTREAM     hStream;       /*  Stream handle. */
  HEVENT      hEvent;        /*  Event handle. */
  ULONG       ulStreamTime;  /*  Time in milliseconds of stream position. */
} SHD_REPORTEVENT;

typedef SHD_REPORTEVENT *PSHD_REPORTEVENT;

Fields

ulFunction (ULONG) Function requested by PDD.

hStream (HSTREAM) Stream handle.

hEvent (HEVENT) Event handle passed back to stream handlers.

ulStreamTime (ULONG) Time in milliseconds of stream position.

SHD_REPORTINT

This data structure contains fields for the SHD_REPORT_INT message.

typedef struct _shd_reportint_parm {
  ULONG       ulFunction;    /*  Function requested by PDD. */
  HSTREAM     hStream;       /*  Stream handle. */
  PVOID       pBuffer;       /*  Return pointer to last used buffer. */
  ULONG       ulFlag;        /*  Reason for interrupt. */
  ULONG       ulStatus;      /*  Return code or bytes read/written. */
  ULONG       ulStreamTime;  /*  Time in milliseconds of stream position. */
} SHD_REPORTINT;

typedef SHD_REPORTINT *PSHD_REPORTINT;

Fields

ulFunction (ULONG) Specifies the function requested by the PDD.

hStream (HSTREAM) Specifies the stream handle so the stream handler knows which stream to process.

pBuffer (PVOID) Returns the pointer to the last used buffer.

ulFlag (ULONG) Specifies the reason for the interrupt. This field defines the following flags:

• ERROR
• STREAM_STOP_NOW
• SHD_READ_COMPLETE
• SHD_WRITE_COMPLETE

Note: Do not set SHD_READ_COMPLETE or SHD_WRITE_COMPLETE if not returning a buffer.

The STREAM_STOP_NOW flag is required. It forces the stream handler to release all buffers that have not been returned. Issue this flag if DDCMD_ STOP or if the VSD has remaining buffers.

ulStatus (ULONG) Specifies the status for the return code or the bytes read or written.

ulStreamTime (ULONG) Specifies the time in milliseconds of stream position.

SHORT

Signed integer in the range -32 768 through 32 767.

#define SHORT short

SPCB

This structure describes a stream protocol of a specific data type.

typedef struct _SPCB {
  ULONG       ulSPCBLen;        /*  SPCB length. */
  SPCBKEY     spcbkey;          /*  SPCB key. */
  ULONG       ulDataFlags;      /*  Data type flags. */
  ULONG       ulNumRec;         /*  Maximum number for records/buffers. */
  ULONG       ulBlockSize;      /*  Block size. */
  ULONG       ulBufSize;        /*  Buffer size. */
  ULONG       ulMinBuf;         /*  Minimum number of buffers. */
  ULONG       ulMaxBuf;         /*  Maximum number of buffers. */
  ULONG       ulSrcStart;       /*  Number of empty buffers. */
  ULONG       ulTgtStart;       /*  Number of full buffers. */
  ULONG       ulBufFlags;       /*  Buffer flags. */
  ULONG       ulHandFlags;      /*  Stream handler flags. */
  MMTIME      mmtimeTolerance;  /*  Resync tolerance value. */
  MMTIME      mmtimeSync;       /*  Sync pulse granularity. */
  ULONG       ulBytesPerUnit;   /*  Bytes per unit. */
  MMTIME      mmtimePerUnit;    /*  MMTIME per unit. */
} SPCB;

typedef SPCB FAR *PSPCB;

Fields

ulSPCBLen (ULONG) Specifies the length of the stream protocol control block.

spcbkey (SPCBKEY) Data stream type and internal key. The internal key is used to differentiate between multiple SPCBs of the same data stream type. User defines should be addressed to 8,000,000(h) and higher.

ulDataFlags (ULONG) Attributes of the data type (that is, it specifies whether data or time cue points are supported by this data type).

• SPCBDATA_CUEDATA :This data type can support data cue-point events.
• SPCBDATA_CUETIME :This data type can support time cue-point events.
• SPCBDATA_NOSEEK :Seeking cannot be done on this data type.
• SPCBDATA_YIELDTIME :This flag indicates that the ulBytesPerUnit field of the SPCB is interpreted as a millisecond yield time value. This yield takes place in between each I/O read operation. The yield time will also dynamically lower during data streaming depending on how many buffers in the stream are full. This flag is mutually exclusive with the SPCBHAND_ GENTIME flag and it can only be used with the SPCBBUF_INTERLEAVED flag. The maximum yield time is 1 second.

ulNumRec (ULONG) Maximum number of records per buffer. (This is valid only for split streams).

ulBlockSize (ULONG) This field can be interpreted in two ways. If the SPCBBUF_INTERLEAVED flag is set, then this field is interpreted as the size of the I/O read operation. This is used to request a read buffer of a smaller size than the ulBufSize field. The source stream handler will take the buffer of ulBufSize and break up the actual I/O reads into ulBlockSize chunks. If ulBlockSize is 1, then the ulBufSize is used as the default I/O read buffer size. Otherwise, ulBlockSize will be the I/O read buffer size. The ulBufSize value must be a multiple of the ulBlockSize value.

The second interpretation of this field is for non-interleaved streams, when the SPCBBUF_INTERLEAVED is not set. The ulBlockSize field represents the atom size of a data item. For example, for digital audio data type PCM 16-bit stereo at a 44.1KB sampling rate, the block size is 4 bytes.

ulBufSize (ULONG) Size of buffer to be used while streaming. Maximum buffer size is 64KB.

ulMinBuf (ULONG) Minimum number of buffers needed to maintain a constant data stream.

ulMaxBuf (ULONG) Maximum (ideal) number of buffers needed. For normal streams, this means the number of buffers that are allocated for the stream . For user-provided buffer streaming, this means the number of buffers that the Sync/Stream Manager can queue for a consumer. This can be used by a source stream handler that gives the same set of buffers to the Sync/Stream Manager repeatedly. If the number of buffers is set to the number of buffers in the set -1, the source stream handler will be able to detect when the target has consumed a buffer so it can be reused. It is assumed that the set of buffers is an ordered set and each buffer is used in the same order each time.

ulSrcStart (ULONG) Number of empty buffers required to start the source stream handler. The value must be at least as big as the maximum number of buffers that would be requested by the source stream handler.

ulTgtStart (ULONG) Number of full buffers required to start the target stream handler. The value must be at least as big as the maximum number of buffers that would be requested by the target stream handler. Usually, a target requires at least two buffers at the start of the stream.

ulBufFlags (ULONG) Buffer attributes (that is, the user provides buffers, fixed block size, interleaved data type, maximum buffer size).

• SPCBBUF_16MEG :The stream buffers can be allocated above the 16MB line. This is used by stream handler device drivers that can support greater than 16MB addresses.
• SPCBBUF_FIXEDBUF :The buffer size for this stream handler must be a particular fixed size (for this data type). The SPCBBUF_INTERLEAVED flag ( split stream) implies SPCBBUF_FIXEDBUF.
• SPCBBUF_INTERLEAVED :This is a split stream. It consists of one input stream of interleaved data that is split into multiple streams of individual data types. Only the source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_USERPROVIDED flag. SPCBBUF _FIXEDBUF cannot be used with this flag set.
• SPCBBUF_MAXSIZE :The ulBufSizefield contains the maximum size buffer that this stream handler can handle.
• SPCBBUF_NONCONTIGUOUS :Each data buffer is allocated contiguously in physical memory unless both stream handlers set the non-contiguous flag ( SPCBBUF_NONCONTIGUOUS). This flag provides the system flexibility in allocating memory. A device driver stream handler might require contiguous memory, while a DLL stream handler might not.
• SPCBBUF_USERPROVIDED :The user provides buffers for streaming. The Sync/ Stream Manager does not allocate buffers but attempts to lock down user- provided buffers or copy the data to locked buffers. Using this flag affects the performance of streaming. Only a source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_INTERLEAVED flag.

ulHandFlags (ULONG) Stream handler flags (that is, handlers can generate/ receive sync pulses, use the Sync/Stream Manager timer as master, and use the non-streaming handler as a NULL handler).

• SPCBHAND_GENSYNC

This stream handler can generate sync pulses.

• SPCBHAND_GENTIME

This stream handler can keep track of the real stream time . This handler also supports the SpiGetTime function and cue point events.

• SPCBHAND_NOPREROLL

This stream handler cannot preroll its device (that is, for recording streams, the source stream handler cannot be prerolled). If asked to preroll this stream, the Sync/Stream Manager treats this stream as if it were prerolled.

• SPCBHAND_NONSTREAM

This stream handler is a non-streaming handler (that is, it is a stream handler that can participate in synchronization but does not stream).

• SPCBHAND_NOSYNC

This stream handler can be in a sync group but does not receive or generate sync pulses. (It is useful to group streams so that they can be manipulated as a group).

• SPCBHAND_PHYS_SEEK

This stream handler does a seek to a physical device. Other stream handlers adjust stream time only on a seek request. The Sync/ Stream Manager always calls this stream handler first in an SpiSeekStream call.

• SPCBHAND_RCVSYNC

This stream handler can receive sync pulses.

• SPCBHAND_TIMER

This stream handler or the device (driver) it communicates with cannot support generation of sync pulses on a granularity necessary for synchronization. Therefore, use the stream manager sync timer as the master timer in a sync group.

mmtimeTolerance (MMTIME) It is used to determine whether to send a sync pulse to a specific slave stream handler.

mmtimeSync (MMTIME) Time interval in Chinatown units between sync pulses. Used to save sync pulse generation granularity if this stream handler is a master but cannot generate its own sync pulse.

ulBytesPerUnit (ULONG) Bytes per unit of time. This is used to do a seek on linear data that is not compressed or of variable length. Also used for SHC_GET_TIME queries in a stream handler.

mmtimePerUnit (MMTIME) The amount of MMTIME each unit represents. This also is used for the SHC_SEEK and SHC_GETTIME messages.

SPCBKEY

This structure identifies a stream protocol.

typedef struct _SPCBKEY {
  ULONG     ulDataType;     /*  Data type for streaming operation. */
  ULONG     ulDataSubType;  /*  Data subtype. */
  ULONG     ulIntKey;       /*  Internal key. */
} SPCBKEY;

typedef SPCBKEY FAR *PSPCBKEY;

Fields

ulDataType (ULONG) Data type for streaming operation. Primary descriptor of the data that will be used in the stream. Possible values can be found in OS2MEDEF.H.

ulDataSubType (ULONG) Secondary descriptor of the data that will be used in the stream.

ulIntKey (ULONG) Contains a unique value used to identify one of several stream protocols of the same data type and subtype.

STATUS_PARM

This data structure contains fields for the pStatusand ulStatusSizefields of the DDCMDSTATUS data structure.

typedef struct _STATUS_PARM {
  ULONG     ulTime;  /*  Current position time in milliseconds. */
} STATUS_PARM;

Fields

ulTime (ULONG) Specifies the current position time in milliseconds.

SZ

Null-terminated string (also known as a zero-terminated string).

typedef CHAR SZ[];

ULONG

32-bit unsigned integer in the range 0 through 4 294 967 295.

typedef unsigned long ULONG;

USHORT

Unsigned integer in the range 0 through 65 535.

typedef unsigned short USHORT;

VCACAPISIZE

typedef struct _VCACAPISIZE {
  ULONG     X_Left;
  ULONG     Y_Top;
  ULONG     Y_Height;
  ULONG     X_Width;
  ULONG     ScaleFactor;
} VCACAPISIZE;

typedef VCACAPISIZE FAR * PVCACAPISIZE;

Fields

X_Left (ULONG)

Y_Top (ULONG)

Y_Height (ULONG)

X_Width (ULONG)

ScaleFactor (ULONG)

VCADEVINFO

typedef struct _vcadevinfo {
  ULONG      Length;           /* Length of structure. */
  CHAR       ProdInfo[30];     /* Describes product information. */
  CHAR       ManInfo[30];      /* Describes manufacturer information. */
  CHAR       Version[10];      /* Describes version information. */
  ULONG      ImgFormat;        /* Image format supported by the card. */
  USHORT     BitsPerPEL;       /* Bits per pel in this image format. */
  USHORT     Overlay;          /* Device has overlay support. */
  ULONG      Brightness;       /* Default brightness value. */
  ULONG      hue;              /* Default hue value. */
  ULONG      saturation;       /* Default saturation value. */
  ULONG      contrast;         /* Default contrast value. */
  ULONG      Sharpness;        /* Default sharpness value. */
  ULONG      unused1;          /* Reserved. */
  ULONG      S_X_Left;         /* Source frame:  default left coordinate. */
  ULONG      S_Y_Top;          /* Source frame:  default top coordinate. */
  ULONG      S_Y_Height;       /* Source frame:  default height coordinate. */
  ULONG      S_X_Width;        /* Source frame:  default width coordinate. */
  ULONG      D_X_Left;         /* Destination frame:  default left coordinate. */
  ULONG      D_Y_Top;          /* Destination frame:  default top coordinate. */
  ULONG      D_Y_Height;       /* Destination frame:  default height coordinate. */
  ULONG      D_X_Width;        /* Destination frame:  default width coordinate. */
  ULONG      D_ScaleFactor;
  ULONG      S_X_MAX;          /* Maximum X size for the digitized source. */
  ULONG      S_Y_MAX;          /* Maximum Y size for the digitized source. */
  ULONG      D_X_MAX;          /* Maximum X size for the destination. */
  ULONG      D_Y_MAX;          /* Maximum Y size for the destination. */
  ULONG      O_X_MAX;          /* Maximum X size for the overlay destination. */
  ULONG      O_Y_MAX;          /* Maximum Y size for the overlay destination. */
  USHORT     VideoInputs;      /* Number of software switchable video inputs. */
  USHORT     CanRestore;       /* Can restore an image on the device. */
  USHORT     CanStretch;       /* Can scale image from source to destination. */
  USHORT     CanDistort;       /* Can scale image without maintaining aspect ratio. */
  USHORT     HasVolume;        /* Video device has volume control. */
  USHORT     HasBalance;       /* Video device has balance control. */
  USHORT     CanScale;         /* Can scale down source image on GetImage IOCtl. */
  USHORT     CanStream;        /* Can do streaming of images to stream handler. */
  ULONG      DI_ulFilenum;     /* File number associated with this instance/open of the device. */
  BYTE       HasTuner;         /* Card has a channel tuner. */
  BYTE       HasTeleTex;       /* Card has teletex support. */
  LONG       Delay_Time;       /* Delay (ms) between connector change/query signal. */
  BYTE       HasAFC;           /* Automatic Frequency Control/FineTune. */
  BYTE       HasPolarization;  /* Support video frequency polarization. */
} VCADEVINFO;

typedef VCADEVINFO FAR * PVCADEVINFO;

Fields

Length (ULONG) Specifies the length, in bytes, of this structure.

ProdInfo[30] (CHAR) String describing product information.

ManInfo[30] (CHAR) String describing manufacturer information.

Version[10] (CHAR) String describing version information.

ImgFormat (ULONG) Indicates image format supported by the card. Valid image formats are:

• DI_IMAGEFORMAT_RGB_565

5 bits of red, 6 bits of green, 5 bits of blue.

• DI_IMAGEFORMAT_YUV_411

YUV_411 bit-interleaved format.

BitsPerPEL (USHORT) Specifies bits per pel in this image format.

Overlay (USHORT) Specifies if the device has overlay support (TRUE or FALSE).

Brightness (ULONG) Specifies the default brightness value (0 to 255).

hue (ULONG) Specifies the default hue value (0 to 255).

saturation (ULONG) Specifies the default saturation value (0 to 255).

contrast (ULONG) Specifies the default contrast value (0 to 255).

Sharpness (ULONG) Specifies the default sharpness value (0 to 255).

unused1 (ULONG) Reserved. Set to zero.

S_X_Left (ULONG) Specifies the default source frame default left coordinate .

S_Y_Top (ULONG) Specifies the default source frame default top coordinate.

S_Y_Height (ULONG) Specifies the default source frame default height coordinate.

S_X_Width (ULONG) Specifies the default source frame default width coordinate.

D_X_Left (ULONG) Specifies the default destination frame default left coordinate.

D_Y_Top (ULONG) Specifies the default destination frame default top coordinate.

D_Y_Height (ULONG) Specifies the default destination frame default height coordinate.

D_X_Width (ULONG) Specifies the default destination frame default width coordinate.

D_ScaleFactor (ULONG) Specifies the default scale factor on a copy action.

S_X_MAX (ULONG) Indicates the maximum X size for the digitized source.

S_Y_MAX (ULONG) Indicates the maximum Y size for the digitized source.

D_X_MAX (ULONG) Indicates the maximum X size for the destination.

D_Y_MAX (ULONG) Indicates the maximum Y size for the destination.

O_X_MAX (ULONG) Indicates the maximum X size for the overlay destination.

O_Y_MAX (ULONG) Indicates the maximum Y size for the overlay destination.

VideoInputs (USHORT) Specifies the number of software switchable video inputs.

CanRestore (USHORT) Indicates if an image can be restored on the device (0= VCAI Play not supported; 1=VCAI Play supported-Start and Data only; 3=VCAI Play supported-Pause/Stop/Flush also supported).

CanStretch (USHORT) Indicates if the image can be scaled from source to destination (TRUE or FALSE).

CanDistort (USHORT) Indicates if the image can be scaled without maintaining aspect ratio (TRUE or FALSE).

HasVolume (USHORT) Indicates if the video device has volume control (TRUE or FALSE).

HasBalance (USHORT) Indicates if the video device has balance control (TRUE or FALSE).

CanScale (USHORT) Indicates if the image can be scaled down on GetImage IOCtl (TRUE or FALSE).

CanStream (USHORT) Indicates if the device supports streaming of images to stream handler (TRUE or FALSE).

DI_ulFilenum (ULONG) This file number is used to associate the stream creation with a particular open instance.

HasTuner (BYTE) Card has a channel tuner.

HasTeleTex (BYTE) Card has teletex support.

Delay_Time (LONG) Delay (ms) between connector change/query signal.

HasAFC (BYTE) Automatic Frequency Control/FineTune.

HasPolarization (BYTE) Support video frequency polarization.

VCAEDCOLORKEY

typedef struct _VCAEDCOLORKEY {
  BOOL     bColorKeying;  /*  1=TRUE=ON, 0=FALSE=OFF. */
} VCAEDCOLORKEY;

typedef VCAEDCOLORKEY FAR * PVCAEDCOLORKEY;

Fields

bColorKeying (BOOL) 1=TRUE=ON, 0=FALSE=OFF.

VCAGETIMAGESCALE

typedef struct _VCAGETIMAGESCALE {
  ULONG     Capture_Buf_Len;  /*  Length, in bytes, of capture buffer. */
  ULONG     Capture_Buf_Ptr;  /*  Pointer to the capture buffer. */
  ULONG     Source_X_Left;    /*  Leftmost pel offset in source frame. */
  ULONG     Source_Y_Top;     /*  Topmost pel offset in source frame. */
  ULONG     Source_Y_Height;  /*  Height of source frame, in pels. */
  ULONG     Source_X_Width;   /*  Width of source frame, in pels. */
  ULONG     Dest_X_Left;      /*  Destination frame's left transpose offset. */
  ULONG     Dest_Y_Top;       /*  Destination frame's top transpose offset. */
  ULONG     Dest_Y_Height;    /*  Height of destination frame in pels. */
  ULONG     Dest_X_Width;     /*  Width of destination frame in pels. */
} VCAGETIMAGESCALE;

typedef VCAGETIMAGESCLAE FAR * PVCAGETIMAGESCALE;

Fields

Capture_Buf_Len (ULONG) Specifies the length, in bytes, of the capture buffer.

Capture_Buf_Ptr (ULONG) Specifies a pointer to the capture buffer.

Source_X_Left (ULONG) Specifies the leftmost pel offset in the source frame .

Source_Y_Top (ULONG) Specifies the topmost pel offset in the source frame.

Source_Y_Height (ULONG) Specifies the height of the source frame, in pels.

Source_X_Width (ULONG) Specifies the width of the source frame, in pels.

Dest_X_Left (ULONG) Specifies the destination frame's left transpose offset .

Dest_Y_Top (ULONG) Specifies the destination frame's top transpose offset.

Dest_Y_Height (ULONG) Specifies the height of the destination frame in pels .

Dest_X_Width (ULONG) Specifies the width of the destination frame in pels.

VCALOAD

This structure contains fields for the VCAI_LOAD_MICROCODE function.

typedef struct _VCALOAD {
  ULONG     ulflags;        /*  1=Query, 2=Load, 3=Unload. */
  CHAR      ProdInfo[256];  /*  Path and name of microcode load. */
  LONG      ulLoadID;       /*  Load ID (returned on Load, sent on Unload). */
  ULONG     ulLength;       /*  Length of load data (sent on Load). */
  PVOID     pLoadData;      /*  Pointer to microcode load data (sent on Load). */
} VCALOAD;

typedef VCALOAD FAR * PVCALOAD;

Fields

ulflags (ULONG) The following flags are defined.

VCALOAD_QUERY     0x01
VCALOAD_LOAD      0x02
VCALOAD_UNLOAD    0x03

ProdInfo[256] (CHAR) If a drive letter (like C:) is not included, the MMPM/ 2 subsystem appends the MMPM/2 base directory (usually "C:/MMOS2/") to the name returned.

ulLoadID (LONG) Load ID (returned on Load, sent on Unload).

ulLength (ULONG) Length of load data (sent on Load).

pLoadData (PVOID) Pointer to microcode load data (sent on Load).

VCAIMAGERF

This structure contains fields for the VCAI_RESTORE_FORMAT function.

typedef struct _VCAIMAGERF {
  ULONG     ulFlags;       /*  0=Query, 1=Set. */
  ULONG     ulNumFormats;  /*  Number of supported formats. */
  ULONG     ulCurIndex;    /*  Current format (or format to set to). */
  ULONG     FourCC[64];    /*  Name of format. */
} VCAIMAGERF;

typedef VCAIMAGERF FAR * PVCAIMAGERF;

Fields

ulFlags (ULONG) The following values are defined for ulFlags.

VCAIRF_Query    0x00
VCAIRF_Set      0x01

ulNumFormats (ULONG) Number of supported formats.

ulCurIndex (ULONG) Current format (or format to set to).

FourCC[64] (ULONG) Name of format.

VCAIMAGECF

This structure contains fields for the VCAI_CAPTURE_FORMAT function.

typedef struct _VCAIMAGECF {
  ULONG     ulFlags;       /*  0=Query, 1=Set. */
  ULONG     ulNumFormats;  /*  Number of supported formats. */
  ULONG     ulCurIndex;    /*  Current format (or format to set to). */
  ULONG     FourCC[64];    /*  Name of format. */
} VCAIMAGECF;

typedef VCAIMAGECF FAR * PVCAIMAGECF;

Fields

ulFlags (ULONG) The following values are defined for ulFlags.

VCAICF_Query   0x00
VCAICF_Set     0x01

ulNumFormats (ULONG) Number of supported formats.

ulCurIndex (ULONG) Current format (or format to set to).

FourCC[64] (ULONG) Name of format.

VCASETCAPTURERECT

typedef struct _VCASETCAPTURERECT {
  ULONG     Source_X_Left;    /*  Leftmost pel offset in source frame. */
  ULONG     Source_Y_Top;     /*  Topmost pel offset in source frame. */
  ULONG     Source_Y_Height;  /*  Height of source frame, in pels. */
  ULONG     Source_X_Width;   /*  Width of source frame, in pels. */
  ULONG     Dest_X_Left;      /*  Destination frame's left transpose offset. */
  ULONG     Dest_Y_Top;       /*  Destination frame's top transpose offset. */
  ULONG     Dest_Y_Height;    /*  Height of destination frame in pels. */
  ULONG     Dest_X_Width;     /*  Width of destination frame in pels. */
} VCASETCAPTURERECT;

typedef VCASETCAPTURERECT FAR * PVCASETCAPTURERECT;

Fields

Source_X_Left (ULONG) Specifies the leftmost pel offset in the source frame.

Source_Y_Top (ULONG) Specifies the topmost pel offset in the source frame.

Source_Y_Height (ULONG) Specifies the height of source frame, in pels.

Source_X_Width (ULONG) Specifies the width of source frame, in pels.

Dest_X_Left (ULONG) Specifies the destination frame's left transpose offset.

Dest_Y_Top (ULONG) Specifies the destination frame's top transpose offset.

Dest_Y_Height (ULONG) Specifies the height of the destination frame in pels.

Dest_X_Width (ULONG) Specifies the width of the destination frame in pels.

VCASETCOLORKEY

typedef struct _VCASETCOLORKEY {
  ULONG     ulColorKey;  /*  Transparent color. */
} VCASETCOLORKEY;

typedef VCASETCOLORKEY FAR * PVCASETCOLORKEY;

Fields

ulColorKey (ULONG) VCASETCOLORKEY value is based on the number of colors supported by the display driver. When in palletized mode (less than or equal to 256 colors), VCASETCOLORKEY is a palette index; when in 16-bit color mode, VCASETCOLORKEY is an RGB-565 color; when in 24-bit color mode, VCASETCOLORKEY is an RGB-888 color.

VCASETFPS

This structure contains fields for the VCAI_SETFPS function.

typedef struct _VCASETFPS {
  ULONG     set_FPS;  /*  Frames per second to stream. */
  ULONG     ulFlags;  /*  Frames or microseconds. */
} VCASETFPS;

typedef VCASETFPS FAR * PVCASETFPS;

Fields

set_FPS (ULONG) Frames per second unless the ulFlags field is set to VCASF_MICROSECONDS-then, the field becomes microseconds per frame.

ulFlags (ULONG) The following ulFlagsare defined:

VCASF_FRAMES        0x0
VCASF_MICROSECONDS  0x1

VCASETMONITOR

typedef struct _VCASETMONITOR {
  BOOL     bMonitor;  /*  1=TRUE=ON, 0=FALSE=OFF. */
} VCASETMONITOR;

typedef VCASETMONITOR FAR * PVCASETMONITOR;

Fields

bMonitor (BOOL) 1=TRUE=ON, 0=FALSE=OFF.

VCASETVIDEO

typedef struct _VCASETVIDEO {
  ULONG     set_brightness;  /*  New overall image brightness setting. */
  ULONG     set_hue;         /*  New image hue (color) setting. */
  ULONG     set_saturation;  /*  New color intensity setting. */
  ULONG     set_contrast;    /*  New contrast setting. */
  ULONG     ret_brightness;  /*  Current overall image brightness setting. */
  ULONG     ret_hue;         /*  Current image hue (color) setting. */
  ULONG     ret_saturation;  /*  Current color intensity setting. */
  ULONG     ret_contrast;    /*  Current contrast setting. */
} VCASETVIDEO;

typedef VCASETVIDEO FAR * PVCASETVIDEO;

Fields

set_brightness (ULONG) Specifies the new overall image brightness setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.

set_hue (ULONG) Specifies the new image hue (color) setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.

set_saturation (ULONG) Specifies the new saturation (color intensity) setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.

set_contrast (ULONG) Specifies the new luminance contrast setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT.

ret_brightness (ULONG) Specifies the current overall image brightness setting. Valid values are 0 to 255 or NOT_SUPPORTED.

ret_hue (ULONG) Specifies the current image hue (color) setting. Valid values are 0 to 255 or NOT_SUPPORTED.

ret_saturation (ULONG) Specifies the current color intensity setting. Valid values are 0 to 255 or NOT_SUPPORTED.

ret_contrast (ULONG) Specifies the current luminance contrast setting. Valid values are 0 to 255 or NOT_SUPPORTED.

VCASETVIDEOINPUT

typedef struct _VCASETVIDEOINPUT {
  ULONG     INPUT_CONNECTOR;  /*  Connector value. */
} VCASETVIDEOINPUT;

typedef VCASETVIDEOINPUT FAR * PVCASETVIDEOINPUT;

Fields

INPUT_CONNECTOR (ULONG) Sets or queries the input connector value. A value of -1 performs a query and returns the current connector value. A value of -2 sets the video input source connector to the default value.

VCASTREAM

This structure contains fields for the VCAI_PLAY function.

typedef struct _VCASTREAM {
  ULONG     ulLength;     /*  Length of image data. */
  PVOID     pImageData;   /*  Pointer to image data. */
  ULONG     ulFlags;      /*  Flag information. */
  ULONG     ulSCR;        /*  MPEG system clock reference (SCR). */
  ULONG     ulPTS;        /*  MPEG presentation time stamp (PTS). */
  ULONG     ulAudioTime;  /*  Current audio stream time. */
} VCASTREAM;

typedef VCASTREAM FAR * PVCASTREAM;

Fields

ulLength (ULONG) Length of image data.

pImageData (PVOID) Pointer to image data.

ulFlags (ULONG) The following flags are defined.

VCA_PLAY_START 0x01 VCA_PLAY_DATA 0x02 VCA_PLAY_STOP 0x04 VCA_PLAY_FLUSH 0x08 VCA_PLAY_PAUSE

ulSCR (ULONG) MPEG system clock reference (SCR). Set to 0 if current packet does not contain a SCR. CODEC-specific, currently used only in split-stream MPEG playback.

ulPTS (ULONG) MPEG presentation time stamp (PTS). Set to 0 if current packet does not contain a PTS. CODEC-specific, currently used only in split-stream MPEG playback.

ulAudioTime (ULONG) Current audio stream time is in MMTIME format on VCA_ PLAY_DATA and in MPEG-90kHz format on VCA_PLAY_START. CODEC-specific, currently used only in split-stream MPEG playback.

VCATUNCHAN

This structure contains fields for the VCAI_TUNERCHANNEL function.

typedef struct _VCATUNCHAN {
  ULONG      ulFlags;      /*  1=Set, 2=Query. */
  ULONG      ulOptions;    /*  Options. */
  USHORT     usResv01;     /*  Reserved. */
  USHORT     usResv02;     /*  Reserved. */
  LONG       lFineTune;    /*  Fine tune value for channel. */
  ULONG      ulFrequency;  /*  Frequency instead of channel/region. */
} VCATUNCHAN;

typedef VCATUNCHAN FAR * PVCATUNCHAN 

Fields

ulFlags (ULONG) The following flags are defined.

TUC_SET_CHANNEL	1
TUC_QUERY_CHANNEL	2

ulOptions (ULONG) The ulOptions field is a bit-sensitive field. The following values are defined for ulOptions.

TUC_AFC_ON	4
TUC_AFC_OFF	0
TUC_FREQUENCY	8
TUC_CHANNEL	0
TUC_POLOARIZATION_VERT	16
TUC_POLOARIZATION_HORI	32

usResv01 (USHORT) Resv01 set to 0.

usResv02 (USHORT) Resv02 set to 0.

lFineTune (LONG) Fine tune value for channel.

ulFrequency (ULONG) Frequency instead of channel/region.

VSD_AUDIOATTRIBUTES_PARMS

This structure contains fields for the VSD_QUERYAUDIOATTRIBUTES command.

typedef struct _VSD_AUDIOATTRIBUTES_PARMS {
  ULONG     ulLength;  /* Length of the structure. */
  ULONG     ulFlags;   /* Attribute to set. */
  ULONG     ulValue;   /* Input/Output.  Value for attribute setting. */
  ULONG     ulDelay;   /* Input.  Delay for attribute setting. */
} VSD_AUDIOATTRIBUTES_PARMS;

typedef VSD_AUDIOATTRIBUTES_PARMS *PVSD_AUDIOATTRIBUTES_PARMS;

Fields

ulLength (ULONG) Length of the structure.

ulFlags (ULONG) Input. The following values are defined for ulFlags.

• VSD_BALANCE :Set or query balance.
• VSD_BASS :Set or query bass.
• VSD_GAIN :Set or query gain.
• VSD_TREBLE :Set or query treble.
• VSD_PITCH :Set or query pitch.

ulValue (ULONG) Input/Output. Value for attribute setting.

ulDelay (ULONG) Delay for attribute setting to take place in mmtime units.

VSD_AUDIODATATYPE_PARMS

This structure contains fields for the VSD_OPEN command.

typedef struct _VSD_AUDIODATATYPE_PARMS {
  ULONG     ulLength;              /*  Length of the structure. */
  ULONG     ulFlags;               /*  Flags. */
  ULONG     ulSamplingRate;        /*  Input.  Sampling rate setting. */
  ULONG     ulBitsPerSample;       /*  Input.  Bits per sample setting. */
  ULONG     ulChannels;            /*  Input.  Channels setting. */
  ULONG     ulBlockAlignment;      /*  Output.  Block alignment. */
  ULONG     ulAverageBytesPerSec;  /*  Output.  Average bytes per second throughput. */
  ULONG     ulDataType;            /*  Input.  Data type to set or query. */
  ULONG     ulDataSubType;         /*  Output.  Data subtype info. */
  ULONG     ulReserved1;           /*  Reserved. */
  ULONG     ulOperation;           /*  Input.  VSD_PRODUCE or VSD_CONSUME. */
  ULONG     ulDeviceID;            /*  Input.  Device ID of the amp-mixer. */
  PVOID     pDevInfo;              /*  Device-specific information. */
} VSD_AUDIODATATYPE_PARMS;

typedef VSD_AUDIODATATYPE_PARMS *PVSD_AUDIODATATYPE_PARMS;

Fields

ulLength (ULONG) Length of the structure.

ulFlags (ULONG) Flags indicating which fields are to be queried or modified. The VSD_AUDIODATATYPE_PARMS structure must contain at least one of the following flags.

Note: More than one flag can be specified.

• VSD_MODE :Set/query mode.
• VSD_CHANNELS :Set/query channels.
• VSD_SAMPLESPERSEC :Set/query sampling rate.
• VSD_BITSPERSAMPLE :Set/query bits per sample.
• VSD_OPERATION :Set/query VSD operation field.

ulSamplingRate (ULONG) Input. Sampling rate setting.

ulBitsPerSample (ULONG) Input. Bits per sample setting.

ulChannels (ULONG) Input. Channels setting.

ulBlockAlignment (ULONG) Output. Block alignment.

ulAverageBytesPerSec (ULONG) Output. Average bytes per second throughput.

ulDataType (ULONG) Input. Data type to set or query. This value is a RIFF datatype (such as DATATYPE_WAVEFORM) defined in OS2MEDEF.H.

ulDataSubType (ULONG) Output. Data subtype info.

ulReserved1 (ULONG) Reserved.

ulOperation (ULONG) Input. Operation to perform; set to either VSD_PRODUCE or VSD_CONSUME.

ulDeviceID (ULONG]]) Input. Device ID of the amp-mixer.

pDevInfo (PVOID) Device-specific information.

VSD_AUDIOOPEN_PARMS

This structure contains fields for the VSD_OPEN command.

typedef struct _VSD_AUDIOOPEN_PARMS {
  ULONG     ulLength;              /* Input.  Length of the structure. */
  ULONG     ulFlags;               /* Input.  Flags. */
  ULONG     ulSamplingRate;        /* Input.  Sampling rate. */
  ULONG     ulBitsPerSample;       /* Input.  Bits per sample. */
  ULONG     ulChannels;            /* Input.  Channels. */
  ULONG     ulBlockAlignment;      /* Input.  Block alignment. */
  ULONG     ulAverageBytesPerSec;  /* Output.  Average bytes per second throughput. */
  ULONG     ulDataType;            /* Input.  Data type to set or query. */
  ULONG     ulDataSubType;         /* Output.  Data subtype info. */
  ULONG     hidSource;             /* Input.  Source stream handler for VSD.  (Unused) */
  ULONG     hidTarget;             /* Input.  Target stream handler for VSD.  (Unused) */
  ULONG     ulOperation;           /* Input.  Operation to perform. */
  ULONG     ulReserved1;           /* Reserved. */
  ULONG     ulDeviceID;            /* Input.  Device ID of the amp-mixer. */
  PVOID     pHeader;               /* Pointer to media-specific header. */
  PVOID     pParmString;           /* Input.  Device-specific parm string. */
  PVOID     pDevInfo;              /* Device-specific information. */
  ULONG     ulReserved2;           /* Reserved. */
  PCHAR     pResourceDLL;          /* Input.  Resource DLL from MMPM2.INI file. */
  ULONG     ulResourceId;          /* Input.  Resource ID to use in Resource DLL. */
} VSD_AUDIOOPEN_PARMS;

typedef VSD_AUDIOOPEN_PARMS *PVSD_AUDIOOPEN_PARMS;

Fields

ulLength (ULONG) Input. Length of the structure.

ulFlags (ULONG) Input. Flags indicating which fields are to be queried or modified. (Unused)

ulSamplingRate (ULONG) Input. Sampling rate.

ulBitsPerSample (ULONG) Input. Bits per sample.

ulChannels (ULONG) Input. Channels.

ulBlockAlignment (ULONG) Input. Block alignment. (Unused)

ulAverageBytesPerSec (ULONG) Output. Average bytes per second throughput.

ulDataType (ULONG) Input. Data type to set or query.

ulDataSubType (ULONG) Output. Data subtype info.

hidSource (ULONG) Input. Source stream handler for VSD. (Unused)

hidTarget (ULONG) Input. Target stream handler for VSD. (Unused)

ulOperation (ULONG) Input. Operation to perform. Defined values for ulOperationinclude VSD_PRODUCE and VSD_CONSUME.

ulReserved1 (ULONG) Reserved.

ulDeviceID (ULONG) Input. Device ID of the amp-mixer. This ID is necessary if media control interface calls must be made by the VSD.

pHeader (PVOID) Pointer to media-specific header. For audio, it is an MMAUDIOHEADER. For further information, see the OS/2 Multimedia Programming Reference. (Unused)

pParmString (PVOID) Input. Pointer to device-specific parmstring in MMPM2. INI file.

pDevInfo (PVOID) Device-specific information.

ulReserved2 (ULONG) Reserved.

pResourceDLL (PCHAR) Input. Resource DLL from MMPM2.INI file. VSD can use this file to retrieve VSD-specific setup information.

ulResourceId (ULONG) Input. Resource ID to use in Resource DLL.

VSD_CONNECTOR_PARMS

This structure contains fields for the VSD_QUERYCONNECTOR message.

typedef struct _VSD_CONNECTOR_PARMS {
  ULONG     ulLength;     /*  Input.  Length of the structure. */
  ULONG     ulFlags;      /*  Flags to be queried or modified. */
  CHAR      ulConn_Type;  /*  Input.  Type of connector. */
  ULONG     ulIndex;      /*  Input.  Connector number. */
  BOOL      fEnabled;     /*  Input/Output.  Indicates enabled or disabled. */
} VSD_CONNECTOR_PARMS;

typedef VSD_CONNECTOR_PARMS *PVSD_CONNECTOR_PARMS;

Fields

ulLength (ULONG) Input. Length of the structure.

ulFlags (ULONG) Flags to be queried or modified.

ulConn_Type (CHAR) Input. Type of connector.

ulIndex (ULONG) Input. Connector number.

fEnabled (BOOL) Input. Indicates if connector is enabled or disabled.

VSD_ESCAPE_PARMS

This structure contains fields for the VSD_ESCAPE message.

typedef struct _VSD_ESCAPE_PARMS {
  ULONG     ulLength;        /*  Length of the structure. */
  PVOID     pBuffer;         /*  Information for VSD. */
  ULONG     ulBufferLength;  /*  Length of pBuffer. */
} VSD_ESCAPE_PARMS;

typedef VSD_ESCAPE_PARMS *PVSD_ESCAPE_PARMS;

Field

ulLength (ULONG) Length of the structure.

pBuffer (PVOID) Information to pass to the VSD.

ulBufferLength (ULONG) Length of pBuffer.

VSD_GETDEVCAPS_PARMS

This structure contains fields for the VSD_GETDEVCAPS message.

typedef struct _VSD_GETDEVCAPS_PARMS {
  ULONG   ulLength;               /* Input. Length of the structure. */
  ULONG   ulMax_Caps;             /* Output. Returns maximum capabilities supported. */
  ULONG   ulNum_Caps;             /* Output. Returns number of capabilities returned. */
  ULONG   ulResv01;               /* Reserved. */
  ULONG   ulResv02;               /* Reserved. */
  ULONG   ulResv03;               /* Reserved. */
  ULONG   ulResv04;               /* Reserved. */
  ULONG   bSupports[DC_MAX_DEVCAP]; /* Output. Capability entries. */
} VSD_GETDEVCAPS_PARMS;

typedef VSD_GETDEVCAPS_PARMS *PVSD_GETDEVCAPS_PARMS;

Fields

ulLength (ULONG) Input. Length of the structure.

ulMax_Caps (ULONG) Output. Returns maximum capabilities supported.

ulNum_Caps (ULONG) Output. Returns number of capabilities returned.

ulResv01 (ULONG) Reserved.

ulResv02 (ULONG) Reserved.

ulResv03 (ULONG) Reserved.

ulResv04 (ULONG) Reserved.

bSupports[DC_MAX_DEVCAP] (ULONG) The following table lists the valid device capabilities.

Device Capabilities	Supported Command
DC_HASAUDIO	All audio functions
DC_HASVIDEO	All video functions
DC_HASVOLUME	VSD_QUERYVOLUME VSD_SETVOLUME
DC_HASDISPLAY	VSD_QUERYDISPLAY VSD_SETDISPLAY
DC_HASAUDIOATTRIBUTES	VSD_QUERYAUDIOATTRIBUTES VSD_SETAUDIOATTRIBUTES
DC_HASAUDIOCAPABILITIES	VSD_QUERYDATATYPE VSD_SETDATATYPE
DC_HASVIDEOATTRIBUTES	VSD_QUERYVIDEOATTRIBUTES VSD_SETVIDEOATTRIBUTES
DC_HASIMAGEATTRIBUTES	VSD_QUERYIMAGEATTRIBUTES VSD_SETIMAGEATTRIBUTES
DC_HASESCAPE	VSD_ESCAPE
DC_HASINPUTLEVEL	VSD_QUERYINPUTLEVEL VSD_SETINPUTLEVEL
DC_HASSTATUSLEVEL	VSD_QUERYSTATUSLEVEL
DC_HASMONITOR	VSD_QUERYMONITOR VSD_SETMONITOR
DC_CANEJECT	VSD_EJECT
DC_CANLOAD	VSD_LOAD
DC_HASDOOR	VSD_QUERYDOOR VSD_SETDOOR
DC_HASTRACKS	VSD_QUERYTRACKS VSD_SETTRACKS
DC_HASMEDIA	VSD_QUERYMEDIATYPE
DC_HASCOMSETTINGS	VSD_QUERYCOMMSETTINGS VSD_SETCOMSETTINGS
DC_HASMEDIATYPE	VSD_QUERYMEDIATYPE
DC_HASKEYLOCK	VSD_QUERYKEYLOCK VSD_SETKEYLOCK
DC_CANCUE	VSD_QUERYCUE VSD_SETCUE
DC_HASCOUNTER	VSD_QUERYCOUNTER VSD_SETCOUNTER
DC_CANRESET	VSD_RESET
DC_HASPOSITION	VSD_QUERYPOSITION VSD_SETPOSITION
DC_HASLENGTH	VSD_QUERYLENGTH VSD_SETLENGTH
DC_CANPARK	VSD_PARK
DC_HASCONNECTOR	VSD_QUERYCONNECTOR VSD_SETCONNECTOR
DC_HASEVENTS	VSD_EVENT
DC_HASDIRECTION	VSD_QUERYDIRECTION VSD_SETDIRECTION
DC_HASVIEWPORT	VSD_QUERYVIEWPORT VSD_SETVIEWPORT
DC_CANCAPTUREIMAGE	VSD_CAPTUREIMAGE
DC_CANRESTOREIMAGE	VSD_RESTOREIMAGE
DC_HASRAM	Informational
DC_AUDIOSETTINGS	Informational
DC_IMAGESETTINGS	Informational
DC_QUERYMINSEEKTIME	Informational
DC_QUERYTIME	Informational
DC_STEP	Informational
DC_CAN_MIX	Mixer functions are available
DC_HASCLOCK	Informational
DC_HASPOWER	Informational
DC_HASZOOM	Informational
DC_HASFOCUS	Informational
DC_HASCHANNELS	Informational
DC_CANSTREAM	VSD_DDCMD
DC_CANSCALE	Informational
DC_CANDISTORT	Informational
DC_CANSTRETCH	Informational
DC_HASTUNER	Informational
DC_HASTELETEX	Informational

Note

Informational in the above table indicates the device has the capability, but does not indicate that a particular command is supported.

VSD_OPEN_PARMS

This structure contains fields for the VSD_OPEN message.

typedef struct _VSD_OPEN_PARMS {
  ULONG   ulLength;                       /* Input. Length of the structure. */
  ULONG   ulCategory;                     /* Name of unit to open. */
  CHAR    szInstallName[MAX_DEVICE_NAME]; /* Installation name of MCD. */
  CHAR    szPDDName[MAX_DEVICE_NAME];     /* Name of PDD to open. */
  HVSD    hvsd;                           /* Output. Handle to the VSD driver. */
  PFN     pfEvent;                        /* Output. (Unused) */
  PVOID   pDevInfo;                       /* Device-specific info. */
  ULONG   ulDDStream;                     /* Input. Device driver stream identifier. (Unused) */
} VSD_OPEN_PARMS;

typedef VSD_OPEN_PARMS *PVSD_OPEN_PARMS;

Fields

ulLength (ULONG) Input. Length of the structure.

ulCategory (ULONG) Input. Name of unit to open. (Currently unused)

szInstallName[MAX_DEVICE_NAME] (CHAR) Input. Installation name of the MCD. This field contains information that can be optionally ignored. (Unused)

szPDDName[MAX_DEVICE_NAME] (CHAR) Input. Name of PDD to open. This field contains information that can be optionally ignored.

hvsd (HVSD) Output. Handle to the VSD driver.

pfEvent (PFN) Output. (Unused)

pDevInfo (PVOID) Input/Output. Device-specific or media-specific information. For audio, it points to VSD_AUDIOOPEN_PARMS

ulDDStream (ULONG) Input. Device driver stream identifier. (Unused)

VSD_RESOURCE_PARMS

This structure contains fields for the VSD_RESOURCE command.

typedef struct _VSD_RESOURCE_PARMS {
  ULONG     ulLength;                    /*  Length of the structure. */
  CHAR      szPDDName[MAX_DEVICE_NAME];  /*  Input.  Device driver name. */
  ULONG     ulDevType;                   /*  Input.  Device type to open. */
  ULONG     ulDataType;                  /*  Input.  Data type to open. */
  ULONG     ulResUnits;                  /*  Output.  Resource units. */
  ULONG     ulClass;                     /*  Output.  Resource class. */
} VSD_RESOURCE_PARMS;

typedef VSD_RESOURCE_PARMS *PVSD_RESOURCE_PARMS;

Fields

ulLength (ULONG) Length of the structure.

szPDDName[MAX_DEVICE_NAME] (CHAR) Input. Name of device driver to open.

ulDevType (ULONG) Input. Device type to open.

ulDataType (ULONG) Input. Data type to open.

ulResUnits (ULONG) Output. Resource units consumed for requested mode.

ulClass (ULONG) Output. Resource class for requested mode (where mode is PCM, MIDI, etc.).

VSD_VOLUME_PARMS

This structure contains fields for the VSD_QUERYVOLUME and the VSD_SETVOLUME commands.

typedef struct _VSD_VOLUME_PARMS {
  ULONG     ulLength;       /*  Length of structure. */
  ULONG     ulFlags;        /*  Volume item to operate on. */
  ULONG     ulRequest;      /*  Unused. */
  ULONG     ulVectoredVol;  /*  Input.  Time for volume change to take place. */
  ULONG     ulMasterAudio;  /*  Input.  Master audio setting. */
  ULONG     ulVolume;       /*  Input/Output.  Volume for connector. */
  ULONG     hConn;          /*  Handle to connector.  (Unused) */
  BOOL      fMute;          /*  Input/Output.  Muted or not muted. */
} VSD_VOLUME_PARMS;

typedef VSD_VOLUME_PARMS  *PVSD_VOLUME_PARMS;

Fields

ulLength (ULONG) Length of structure.

ulFlags (ULONG) Input. Volume item to operate on.

The following flags (subcommands) are defined for this command:

• VSD_VOLUME Instance volume.
• VSD_MASTERVOLUME System-wide volume setting.
• VSD_MUTE Flag indicating mute setting.

ulRequest (ULONG) Unused.

ulVectoredVol (ULONG) Input. Time for volume change to take place.

ulMasterAudio (ULONG) Input. Master audio setting.

ulVolume (ULONG) Input/Output. Volume for connector.

hConn (ULONG) Handle to connector to operate on. (Unused)

fMute (BOOL) Input/Output. Indicates if volume should be muted.

VOID

A data area of undefined format.

#define VOID void