TECHNICAL MANUAL
Rockwell International
Newport Beach
Multimedia Communications Division
Draft Revision 1.44
Released: October 13, 1993
1. Integrate the document conventions section of the FAPI Technical Manual with the document. Describe the available memory models.
2. Expand error codes as needed after performing final code reviews.
3. Complete the section describing each member of the Rockwell RIFF Formatted Voice File Structure JYW.
4. Complete the section describing the defined error codes for each RIFF function JYW.
1. Added decimation function for down-sampling from 44100 to 11025 Hz.
The following are found on the distribution disks.
File Name File Description Used
EXAMPLE1.C Example VAPI implementation for handset Both
EXAMPLE2.C Example VAPI implementation for answer machine Both
EXAMPLE4.C Example VAPI implementation for answer machine Both
with call discrimination capability
RAWAUTL1.C Utility functions Windows
RAWAUTL2.C Utility functions Windows
RAWCNFIO.C WVAPIMN.EXE configuration file I/O functions Windows
RAWDLG1.C WVAPIMN.EXE dialog box management functions Windows
RAWDLG2.C WVAPIMN.EXE dialog box management functions Windows
RAWDLG3.C WVAPIMN.EXE dialog box management functions Windows
RAWDLG4.c WVAPIMN.EXE dialog box management functions Windows
RAWDLLMN.C DLL initialization functions Windows
RAWDOS.C Windows File I/O primitives Windows
RAWDSPLY.C Windows diagnostic display functions Windows
RAWDTAPI.C Data structure initialization code Windows
RAWDTAPP.C Data structure initialization code Windows
RAWDUTL1.C DLL utility functions Windows
RAWERR.C WVAPIMN.EXE error reporting module Windows
RAWIO.C Window file I/O functions Windows
RAWMAIN.C WVAPIMN.EXE "WinMain" application Windows
initialization
RAWSDIO1.C "wputs" diagnostic display functions Windows
RAWSDIO2.C "wputs" diagnostic display functions Windows
RAWSESS.C Session level functions for VAPI.DLL Windows
RAWTUTL1.C Data structure initialization code for Windows
WVAPIMN.EXE
RAWVDSPL.C Window diagnostic display functions Windows
RAWVSESS.C Session level functions for VAPI.DLL Windows
RAWVUTL1.C Data structure initialization code for Windows
WVAPIMN.EXE
RAWWSIO.C Window serial IO functions Windows
VAPIDSPL.C DOS diagnostic display functions DOS
VAPISESS.C DOS voice session functions DOS
VCALLBKE.C VAPI callback function Both
RAWSDIO.D "wputs" header file Windows
RAWAPISD.DEF Module definition file for RAWAPISD.DLL Windows
RAWV.DEF Module definition file for WVAPIMN.exe Windows
ABOUT.DLG Dialog box resource script Windows
ASCIFORM.DLG Dialog box resource script Windows
CANCEL.DLG Dialog box resource script Windows
DIALSTR.C Dialog box resource script Windows
FAXMODEM.DLG Dialog box resource script Windows
FILENAME.DLG Dialog box resource script Windows
LOGENV.DLG Dialog box resource script Windows
OPENFILE.DLG Dialog box resource script Windows
RECEIVE.DLG Dialog box resource script Windows
SAVEFILE.DLG Dialog box resource script Windows
SUBID.DLG Dialog box resource script Windows
XMITLIST.DLG Dialog box resource script Windows
RAWAPISD.DLL Window display DLL Windows
VAPI.DLL VAPI DLL Windows
VAPIRIFF.DLL RIFF file DLL Windows
ZAPI.DLL ZAPI DLL Windows
EXAMPLE.H Header file for all example modules Both
FAPI.H Header file for FAPI.C Both
FAXFILE.H Header file for FaxFile module Both
PRINT.H Header file for print Module Windows
RAW.H Primary header file for WVAPIMN.C Windows
RAWERR.H Header file for WVAPIMN.C Windows
RAWGLOBL.H Header file for WVAPIMN.EXE global variables Windows
RAWSDIO.H Header file for diagnostic display functions Windows
RAWVOICE.H Header file for VAPI.DLL Windows
RIF.H Header file for RIFF File Both
VAPI.H Header file for VAPI Both
VCALLBK.H Header file for VAPI Callback functions Both
ZAPI.H Header file for ZAPI functions DOS
ZAPIDOS.H Header file for ZAPI DOS I/O functions DOS
RAW.ICO WVAPIMN.EXE ICO file Windows
MRVAPI.LIB Object module library for the VAPI in MSC DOS
medium memory model format
MRVRIF.LIB Object module library for the RIFF file I/O in DOS
MSC medium memory model format
MRZAPI.LIB Object module library for the ZAPI in MSC DOS
medium memory model format
RFRAWDLL.LIB Import library for RAWAOISD.DLL Windows
RVAPIDLL.LIB Import library for VAPI.DLL Windows
RVRIFDLL.LIB Import library for VAPIRIFF.DLL Windows
RZAPIDLL.LIB Import library for ZAPI.DLL Windows
SRFSTRW.LIB Object library contain the startup object Windows
routines common to Rockwell DLLs
DOSVAPI.MAK Makfile for EXAMPLE1.EXE EXAMPLE2.EXE and DOS
EXAMPLE4.EXE
RAWAPISD.MAK Makefile for DLL Windows
RAWV.MAK Makefile for WVAPIMN.EXE Windows
MAKEFILE Master makefile Both
RAWAPISD.RC Resource script Windows
RAWERR.RC Resource script Windows
RAWV.RC Resource script Windows
LIBENTRY.ASM Start code for DLLs Windows
The following executables are buildable from the basic release.
File Name File Description Used
EXAMPLE1.EXE Example VAPI implementation for handset DOS
EXAMPLE2.EXE Example VAPI implementation for answer machine DOS
EXAMPLE4.EXE Example VAPI implementation for answer machine DOS
with call discrimination capability
WVAPIMN.EXE Example Windows test program. Windows
2.2. Special Release
Note that the following items do not come in the basic package; special arrangements are necessary before these functions are release in object. Source for the kernel VAPI functions, not including the test harness and developer's functions, always take special arrangements.
File Name File Description Used
D.OBJ Object module for ADPCM and small filter DOS
sample rate change routines. Small Memory
Model.
DB.OBJ Object module for ADPCM and large filter DOS
sample rate change routines. Small Memory
Model.
DM.OBJ Object module for ADPCM and small filter DOS
sample rate change routines. Medium Memory
Model.
DBM.OBJ Object module for ADPCM and large filter DOS
sample rate change routines. Medium Memory
Model.
DMAIN.C Test Harness for ADPCM and sample rate change DOS
routines.
SRVRIF.LIB Rockwell's RIFF file functions for voice. DOS
RIF.H Header file for RIFF file functions for voice. DOS
D.MAK Make file for DMAIN and DMAINB. DOS
DMAIN.EXE Test Harness for ADPCM and small filter sample DOS
rate change routines. Small Memory Model.
DMAINB.EXE Test Harness for ADPCM and large filter sample DOS
rate change routines. Small Memory Model.
DMAINM.EXE Test Harness for ADPCM and small filter sample DOS
rate change routines. Medium Memory Model.
DMAINBM.EXE Test Harness for ADPCM and large filter sample DOS
rate change routines. Medium Memory Model.
3. Definitions and Assumptions
This document makes extensive reference to the following specifications
1. Rockwell's specification -- Voice in the AC Products (Version April, 1992) Voice in the AC Products (Version April, 1992).
2. Rockwell's specification -- General I/O Functions (Version 1.10) General I/O Functions (Version 1.10).
The term Polling Commands, used in the function definitions below, indicate that the final result of the function is not known after the functions return back to the caller. The final result is only known after two conditions are met. First, the API is polled many times, by use of the RVPoll() function. Second, the API returns a non-zero status code by way of the RVStatus() function to indicate completion.
As a reminder, the API must be polled many times in order to give the API the opportunity to command and to solicit responses from the DCE. The final result is only known after the API has made all of its intended DCE interactions, or until the API have encountered an error. The functions, listed below, may return an error immediately after the call, but this is the result of parameter checking and does not involve any interaction with the DCE.
This specification assumes that the DCE can enter various modes. These modes are listed below:
Mode Number Description
Data 0 Traditional data modem functions. Use AT+CLS=0
to enter this mode. Equivalent to AT+FCLASS=0.
Facsimile 1 or 2 Service Class 1 (EIA-572) or Service Class 2
facsimile mode. Use AT+CLS=1 or AT+CLS=2 to
enter this mode. Equivalent to AT+FCLASS=1 and
AT+FCLASS=2 respectively.
Voice 2 Voice activities. Use AT+CLS=8 to enter this
mode.
This specification assumes that the DTE software driving the VAPI ("DTE Software") will first enter the Voice Mode, do voice related activities such as setup and voice I/O, and then leave the Voice Mode. The "DTE Software" may do other activities after leaving the Voice Mode, such as going to some kind of idle state, entering a Facsimile mode or some other Data Mode. The primary reason for this compartmentalization of functionality (Voice, Facsimile, and Data) is -- (1) simplicity in DCE implementation; (2) for compatibility with Windows; and (3) for predictability of operation. Examples are -- (a) for compatibility, a Voice Mode that avoids constantly changing baud rates, such as would occur for voice record and playback, because Windows takes 600 to 800 milliseconds (ms) to change the state of the UART; and (a) for predictability, some operation in voice, such as DTMF detection with unsolicited event detection codes, would be incompatible with most other modes, such as facsimile as specified in Service Class 1 or Service Class 2 (pending).
The term, BPS, is used through out this document to indicate both the compression method, and bits per sample selection as per the AT+VBS definition contained in Rockwell's specification - Voice in the AC Products (Version April, 1992).
This specification assumes that the "DTE Software" will first enter the Voice Mode, do voice related activities such as setup and voice I/O, and then leave the Voice Mode. The setup activities would involve querying the DCE as to its voice capabilities, such as compression method, bits per sample (BPS), and so forth. These results would be saved for later voice record and playback.
This specification presumes that the following functions are called to ascertain the DCE capabilities:
Voice Function Description
RVSetVMBaudRate() Enter the Voice Mode and change the baud rate.
RVGetBPSRange() Get all of the DCE supported BPS's and other
related information. The "DTE Software" has
the opportunity at this time to create a VCI
structure array. See page 17 for the
definition of the VCI structure.
RVGetCMIdRange() Get all of the DCE supported compression method
identifiers. The "DTE Software" can create an
array of identifier strings at this point.
RVGetVLRange() Get all of the DCE supported Voice I/O Line
information. The "DTE Software" can create an
array of voice line capabilities at this point.
RVSetVMBaudRate() Exit the Voice Mode and change the baud rate.
The following is an example to show the calling sequence to answer the phone and record a message:
Voice Function Description
RVSetVMBaudRate() Enter the Voice Mode and change the baud rate.
RVSetCurrentMode() Allows the API to quickly select among various
voice capability options.
RVAnswerCD() Answer the phone and attempt to identify the
remote station - Voice, Facsimile, or Data.
Other Voice Operations
RVSetVMBaudRate() Exit the Voice Mode and change the baud rate.
3.6. Immediate Error
The term, Immediate Error, means that the API has performed parameter checking, but has not done any interaction with the DCE to determine if any of the parameters are not supported by the DCE. Not implemented in the current release. Currently, the functions return zero with the non-zero values reserved for future implementation.
Tone detection is an important part of the VAPI operation. The VAPI provides structures and bit fields that control the detection and reporting of DTMF/Tone detection events.
The usual procedure is for the "DTE Software" to first inquire about the DCE DTMF/Tone detection capability, mask out unwanted event detection messages (optional, the "DTE Software" could just ignore the messages), and, perhaps in certain times, inquire about the current mask. The individual DTMF/Tones are represent in the commands and reports with individual bits. Note that the first "DTE Software" inquiry about the DCE DTMF/Tone detection capability is actually three steps -- one possible distinct capability for the voice transmit, receive, and the idle mode.
The VAPI document frequently describes commands and reports that use the three operations mentioned above. These operations are -- (1) the "Best DTMF/Tone Detection Capability" of the DCE; (2) the "DTMF/Tone Detection Mask"; and (3) the "Current Setting of the DTMF/Tone Detection Capability" of the DCE. See Table 4, page 13, for the definition of the phrases.
1 The "Best DTMF/Tone Detection Capability" of the DCE refers to
the maximum DTMF/Tone detection capability of the DCE. This
detection capability may be different for playback, record, and
idle.
The API gets this information by issuing the AT+VTD=? command.
2 The "DTMF/Tone Detection Mask" refers to which DTMF/Tone(s) the
DTE does not wish reported. The "DTE Software" may use different
masks, to limit DTMF/Tone detection, for playback, record, and
idle. Note that the DTE may re-enable previously disabled
capabilities. Note that the DTE cannot enable capabilities not
listed in the report of the "Best DTMF/Tone Detection
Capability".
A bit value of 1 indicates that the capability should be enabled,
if possible, and a value of 0 indicates that the capability
should be disabled.
The API sets the DCE masks by issuing the
AT+VTD=<Value>,<Value>,<Value> command.
3 The "Current Setting of the DTMF/Tone Detection Capability" of
the DCE refers to which DTMF/Tone(s) the DCE will report. This
is a result of the "Best DTMF/Tone Detection Capability" of the
DCE disabled by the DTE by some previous masking operation.
The API gets this information by using the AT+VTD? command.
The masking and reporting of DTMF/Tone detection capabilities is performed through the use of predefined bit fields placed in the AT command string; Table 5, page 14, defines the bit field assignments at the time of this document's creation. The final source on the bit fields is the Rockwell specification -- Voice in the AC Products (Version April, 1992). The reader should refer to this document for the current definition.
Currently, only the 4.1.2. VTD Structure uses these bits.
Bit Description
0 If set, enables DTMF Detection.
1 If set, enables CCITT Calling Tone V.25 - 1300 Hz (Data
Modem).
2 If set, enables CCITT T.30 - 1100 Hz (Facsimile Modem).
3 If set, enables CCITT V.25/T.30 Answer Tone - 2100 Hz (Data
or Facsimile Modem).
4 If set, enables Bell 2225 Hz Answer Tone (Data Modem).
5 If set, enables DCE detection and reporting of call
progress tones and cadences, such as busy and dial tones,
via <DLE> codes.
6-7 Reserved.
3.8. RIFF File Format
This specification assumes all voice file formats are using the Rockwell RIFF file format. See the "RIFF File Functions" chapter (page 45) for more details.
Voice Parameter Information. This structure is used for setting and retrieving voice parameters. A value of -1 in any structure member informs the API not to attempt to change the given setting in the DCE. A value of -1 for a DCE retrieve operation has no meaning.
struct VPS
{
int BPS;
long SampleRate;
int SilenceSensitivity;
int SilenceDeletion;
int SilenceDetectPeriod;
int VoiceLine;
};
Structure Member Description
int BPS Compression method and bits per sample.
long SampleRate Sample rate.
int SilenceSensitivity; Silence Sensitivity tuner value
int SilenceDeletion Silence deletion enable/disable flag
nt SilenceDetectPeriod Silence detection period (inactivity timer)
value
int VoiceLine Voice I/O line.
4.1.2. VTD Structure Definition
Voice Tone Detection. This structure is used for setting and retrieving DTMF/Tone detection and call progress tone detection parameters. A value of -1 in any structure member informs the API not to attempt to change the given setting in the DCE. A value of -1 for a DCE retrieve operation has no meaning.
struct VTD
{
unsigned int TxTD;
unsigned int RxTD;
unsigned int IdleTD;
};
The three members reflect that there may exist three distinct DCE DTMF/Tone detection capabilities for the voice transmit, receive, and idle mode. See the "DTMF/Tone Detection" section on page 13 for more details. The final source on the bit fields is the Rockwell's specification -- Voice in the AC Products (Version April, 1992).
Note that the ToneDetectionCaps member of the VCI structure is the "Best DTMF/Tone Detection Capability" of the DCE at the selected BPS.
struct VCI
{
unsigned int BPS;
unsigned long SampleRateLow;
unsigned long SampleRateHigh;
unsigned int SilenceSensitivityLow;
unsigned int SilenceSensitivityHigh;
struct VTD ToneDetectionCaps;
};
See page 15 for the definition of the VTD structure.
Structure Member Description unsigned int BPS Compression method and bits per sample. unsigned long Low bounds for the sample rate. SampleRateLow unsigned long High bounds for the sample rate. SampleRateHigh unsigned int Low bounds for the silence deletion SilenceDeletionLow sensitivity. unsigned int High bounds for the silence deletion SilenceDeletionHigh sensitivity. struct VTD far The "Best DTMF/Tone Detection Capability" of *ToneDetectionCaps the DCE.
4.1.4. VFC Structure Definition
struct VFC
{
int ValidFileFlag;
unsigned int BPS;
unsigned long SampleRate;
unsigned int SilenceDeletion;
unsigned int VoiceFileNameIndex;
unsigned char far *CMIdString;
unsigned int CMIdIndex;
};
Structure Member Description
int ValidFileFlag Zero if the file, pointed to by the
VoiceFileName parameter, is a valid Rockwell
RIFF file and if the embedded voice mode
parameters in the file, such as BPS, is
supported by this DCE. This parameter is 1 if
the voice file in question is valid, but the
DCE does not support the voice mode parameters.
Any other non-zero value for this parameter
indicates that the API could not gain any
useful information from the file. The rest of
the voice mode parameters for this callback
function are therefore undefined.
The API uses the array of VCI structures, and
the array of compression method identifier
strings as the representation of the DCE's
capabilities. It is important that this list
is correct and up to date.
unsigned int BPS Compression method and bits per sample if the
file is a valid voice file.
unsigned long Sample rate if the file is a valid voice file.
SampleRate
unsigned int Silence deletion sensitivity level if the file
SilenceDeletion is a valid voice file.
unsigned int Index number of the VoiceFile array list that
*VoiceFileNameIndex the API is checking.
unsigned char far ASCIIZ compression method identifier string.
*CMIdString The possible compression methods are DCE
specific. The compression method identifier is
covered in Rockwell's specification - Voice in
the AC Products (Version April, 1992).
If this parameter is null, this indicates that
the API has found a matching compression method
identifier string embedded in the voice file,
given by the VoiceFileNameIndex parameter, to
one of the identifiers on the CMIdString list.
The identifier's index is given by the
CMIdIndex parameter.
If the parameter is not null, the API has not
found a match on the CMIdString list. This
parameter points to the name found in the voice
file. This pointer is only valid during the
call. The "DTE Software" should make a local
copy of the ASCIIZ string. The CMIdIndex
parameter is undefined in this case. The API
considers this an error condition.
unsigned int CMIdIndex If CMIdString parameter is null, the CMIdIndex
parameter is the index into CMIdString list of
the RVCheckVoiceFiles() call. Note that the
CMIdString parameter name is used in both the
original call and the callback function.
Otherwise, the CMIdIndex parameter is
undefined.
4.2. RADPCMVOICE Structure Definitions
Unless otherwise noted the structures specified in this section are identical to those specified in the Microsoft Multimedia Software Developer's Kit. The Rockwell file format is an extension of Microsoft's Waveform Audio File Format (WAVE).
struct _MMCKINFO
{
FOURCC ckid;
DWORD cksize;
FOURCC fccType;
DWORD dwDataOffset;
DWORD dwFlags;
}
Structure Member Description
FOURCC ckid Four character ASCII sequence encoded in an
unsigned long.
DWORD cksize Specifies the size of the data field of the
chunk. The size of the data field does not
include the four-byte chunk ID, the four-byte
chunk size, or the optional pad byte at the end
of the data field.
FOURCC fccType Specifies the form type for "RIFF" chunks or
the list type for "LIST" chunks.
DWORD dwDataOffset Specifies the file offset of the beginning of
the chunk's data field, relative to the
beginning of the file.
DWORD dwFlags Specifies flags giving additional information
about the chunk. Contains zero or more of the
following flags:
MMIO_DIRTY: Indicates the the length of the
chunk may have changed and should be udpated by
mmioAscend. This flag is set when a chunk is
created by mmioCreateChunk.
4.2.2. _WAVEFORMAT Structure Definition
struct _WAVEFORMAT
{
WORD wFormatTag;
WORD nChannels;
DWORD nSamplesPerSec;
DWORD nAvgBytesPerSec;
WORD nBlockAlign;
}
Structure Member Description
wFormatTag A number which indicates the WAVE format
category of the file. The format specific
information is described in the
nChannels The number of channels represented in the Data
Chunk of the WAVE file, such as 1 for mono, or
2 for stereo.
nSamplesPerSec The sampling rate (in samples per second) that
each channel should be played back at.
nAvgBytesPerSec The average number of bytes per second that
data in the Data Chunk should be transferred
at.
nBlockAlign The block alignment (in bytes) of the data in
the Data Chunk.
4.2.3. _RADPCMWAVEFORMAT Structure Definition
This structure is contained in the Format Chunk.
struct _RADPCMWAVEFORMAT
{
WORD wBitsPerSample;
WORD wSilenceDeletion;
char szCompIdStr[LEN_CMIDSTR];
}
Structure Member Description
wBitsPerSample The number of bits per sample of compressed
audio data (ADPCM).
wSilenceDeletion Indicates the silence deletion setting used to
record the audio signal.
szCompIdStr A character string identifying the compression
algorithm used to compress the audio signal.
4.2.4. _PCMWAVEFORMAT Structure Definition
This structure is contained in the Format Chunk.
struct _PCMWAVEFORMAT
{
WORD wBitsPerSample;
}
Structure Member Description
wBitsPerSample The number of bits per sample of uncompressed,
PCM sampled audio data.
4.2.5. _RADPCMWAVEFORMAT Structure Definition
This structure is passed as the parameter to and maintained by the VF_Functions -- VF_OpenVoice(), VF_ReadVoice(), VF_WriteVoice(), and VF_CloseVoice()
struct _RADPCMWAVEFORMAT
{
MMCKINFO ckParent;
MMCKINFO ckFmt;
MMCKINFO ckData;
HMMIO hFileHandle;
WAVEFORMAT wf;
union _WAVEFORMATSPEC
{
RADPCMWAVEFORMAT rwf;
PCMWAVEFORMAT pwf;
};
};
Structure Member Description
ckParent Contains the RIFF WAVE "form" chunk. This
MMCKINFO structure is described earlier in this
section.
ckFmt Contains the Format chunk which points to the
_WAVEFORMAT and _WAVEFORMATSPEC structures.
This MMCKINFO structure is described earlier in
this section.
ckData Contains the Data chunk which points to the
WAVE data. The MMCKINFO structure is described
earlier in this section.
hFileHandle Contains the DOS file handle created when
opening the RIFF file.
wf Contains the WAVE format data pointed by the
ckFmt chunk. The _WAVEFORMAT structure is
described eariler in this document.
rwf OR pwf Contains either the _RADPCMWAVEFORMAT or the
_PCMWAVEFORMAT structures depending on the type
(wFormatTag) of RIFF WAVE file being read.
The VAPI call back function, described in this section, is the primary means of updating application software on the current state of the VAPI. Identifier codes are defined to describe the content of each call and allow the use of one function for the notification of all events. The application software which processes the data defined for each identifier must minimize the delay in returning control to the VAPI. It is recommended that this function simply update local copies of state variables and that further processing be directed to occur between calls to the VAPI polling function RVPoll() (the function used to sustain VAPI state transition).
When using the VAPI MS Windows DLL's, the application software must be certain to follow the Windows convention of exporting functions which will be called from a different code segment. No special provision for the the DOS equivalent of this function is necessary.
The pointer to data defined in certain CallBack Identifier Codes is valid only for the duration of the call to the callback function. The "DTE Software" should make a local copy of this data if required for later use.
int FAR PASCAL RVCallBack(
int id, long Parm);
Type/Parameter Description
int id; Identifier for the nature of the Parm variable,
and the indicator for the expected return
value.
long Parm; Can be a variable or a far pointer depending of
the value of id.
Code Parm Return Value
RV_CB_TONE_IDLE int Tone; 0
RV_CB_TONE_RX int Tone; Return 1 to close down
Voice operation,
otherwise return 0.
RV_CB_TONE_CD int Tone; Return 0 for Voice, 1
for facsimile, 2 for
data, or -1 for not a
clue.
RV_CB_VPS struct VPS far 0
*VoiceParmInfo;
RV_CB_VTD struct VTD far 0
*ToneDetectionInfo;
RV_CB_CMID unsigned char far Return 1 for no more
*CMIdString; callbacks, otherwise
return 0.
RV_CB_VCI struct VCI far Return 1 for no more
*VoiceCapsInfo; callbacks, otherwise
return 0.
RV_CB_VLA unsigned int Return 1 for no more
VoiceLineAttribute; callbacks, otherwise
return 0.
RV_CB_BR unsigned int BaudRate 0
RV_CB_VCF struct VFC far 0
*VoiceCheckFile;
RV_CB_LOCK_MEM long Handle; Return 0 for success.
RV_CB_UNLOCK_MEM long Handle; Return 0 for success.
Closing down the voice operation may include closing the transmit files, and the receive files for the case of Voice I/O performed from files, or may include unlocking and releasing memory buffers.
The following table presents the general rules the application software can use to classify the return values from the API. These return values apply for both the immediate returns, and the return status from RVStatus().
Value Description
0 Indicates that, at the time of this call to
RVStatus(), the API has not completed its series of
operations with the DCE.
Greater than 0 Indicates that the API has completed its series of
operations with the DCE, and that the API did not
encounter any errors.
Less than 0 Indicates that the API has completed its series of
operations with the DCE, and that the API did
encounter a error.
The following table presents the normal non-error result code that most of the API functions return immediately after the call. This value can be considered as meaning that the final result code is not known. This is normal for the API functions that must used in conjunction with the RVPoll() function.
API functions that do run to completion before returning (not needing RVPoll()), also return this value to indicate that no errors occurred. Positive values indicate additional information the API reports to the application. In most cases, this additional information is not needed. Negative values indicate an error.
As a reminder, the status code returned immediately after the API function call does not represent the final result code of the operation. The final result code is only returned after repeated calls to RVPoll() API function. This result code is also returned by the RVStatus() call to indicate that the operation is not yet completed. Most of the API functions only begin an operation that repeated calls to RVPoll() finishes. The defined RVStatus() result codes are listed in the following tables.
Returned Status Description
RV_STATUS_NONE No immediate error. The
application should use RVStatus()
to poll the status of the DTE/DCE
transaction.
Table 7. - Normal Termination CodesNormal Termination Codes
Returned Status Description
RV_STATUS_DONE This code indicates that the
processing associated with the
previously executed function is
complete. It should not, however,
be used as an indication of success
or failure. The current list of
available error codes will be
expanded to include specific
processing errors in a future
release.
RV_STATUS_DONE_CD_PLAY This is an interim result code,
and it is returned while the VAPI
is processing the AnswerCD
function. This code indicates that
VAPI has completed the initial
outgoing message and is continuing
the discriminating process
RV_STATUS_DONE_CD_RECORD This result code is returned when
VAPI is processing the AnswerCD
function. The code indicates that
VAPI has detected and completed
the recording of an incoming voice
call.
RV_STATUS_VOICE This result code is returned when
VAPI is processing the AnswerCD
function. The code indicates that
VAPI has detected an incoming
voice call and is currently
recording the incoming call. Note:
This result code is not yet
implemented in VAPI
RV_STATUS_DATA This result code is return when
VAPI is processing the AnswerCD
function. This code indicates that
VAPI has detected an incoming data
call.
RV_STATUS_FAX This result code is return when
VAPI is processing the AnswerCD
function. The code indicates VAPI
has detected an incoming fax call.
RV_STATUS_UNKNOWN This result code is return when
VAPI is processing the AnswerCD
function. The code indicates that
VAPI is unable to determine the
identity of the incoming call.
Note: The code in not yet
implemented in VAPI
RV_STATUS_TIMEOUT This code indicates that the
processing associated with the
previously executed function was
aborted due to the expiration of an
internal event timer.
Table 8. - Abnormal Termination CodesAbnormal Termination Codes
Returned Status Description
RV_ERR_GEN_WRONG_TOKEN This code indicates that the AT
command response string received
was incorrect.
RV_ERR_GEN_NO_RESPONSE This code indicates that the modem
is not responding to the commands
submitted.
RV_ERR_GEN_NO_SUCH_FILE This code indicates that the file
specified in a previously executed
function does not exist.
RV_ERR_GEN_NOT_A_RIFF_FILE This code indicates that the file
specified in a previously executed
function was not a RIFF formatted
file.
RV_ERR_GEN_APP_ABORT This code indicates that an abort
sequence was initiated by the
application.
RV_ERR_GEN_INTERNAL This code indicates that an
internal API error has occurred.
Returned Status Description
RV_ERR_INV_BPS This code indicates that the data
rate parameter of the API function
called was invalid.
RV_ERR_INV_SAMPLE_RATE This code indicates that the sample
rate parameter of the API function
called was invalid.
RV_ERR_INV_SILENCE_SENSITIVITY This code indicates that the
silence sensitivity parameter of
the API function called was
invalid.
RV_ERR_INV_SILENCE_DETECT_PERIOD This code indicates that the API
function parameter defining the
period of silence required to
generate a response string was
invalid.
RV_ERR_INV_SILENCE_DELETION This code indicates that the API
function parameter defining the use
of silence deletion was invalid.
RV_ERR_INV_VOICE_LINE This code indicates that the voice
line selected in calling a
specified API function was invalid.
RV_ERR_INV_TONE_DETECTION This code indicates that the tone
detection parameter of the API
function called was invalid.
RV_ERR_INV_BAUDRATE This code indicates that the data
rate parameter of the API function
called was invalid.
RV_ERR_INV_PARAM This code indicates that an
unspecified parameter in the API
function called was invalid.
RV_ERR_INV_CLASS This code indicates that the
service class selected during the
activation of voice capabilities
was invalid.
RV_ERR_DEV_INV_IRQ_BUF This code is reserved for use by
the developer to indicate that an
invalid buffer size was requested.
RV_ERR_DEV_INV_COM_ID This code is reserved for use by
the developer to indicate than an
invalid COM port ID was requested.
The error codes preceded by an "MMIO" are identical to those described in the Microsoft Windows Multimedia Software Development Kit (included in the 3.1 release of the SDK). The error codes preceded by a "VF" indicate extended error codes describing errors which occur in the use of the high level RIFF functions VF_OpenVoice(), VF_CloseVoice(), VF_ReadVoice(), and VF_CloseVoice(), described in the "RIFF File Functions" section starting on page 45.
MMIO errors occur in the lower level RIFF I/O functions specified by Microsoft in the Multimedia SDK and called by the VF_ level functions. These codes are passed up to the caller of the VF_ level functions.
Returned Status Description
MMIO_OUTOFMEMORY The new buffer could not be
allocated, probably due to a lack
of available memory.
MMIOERR_CANNOTWRITE The cotents of the old buffer could
not be written to disk and resulted
in aborting the write.
MMIOERR_CANNOTSEEK There was an error while seeking to
the end of the chunk.
MMIOERR_CHUNKNOTFOUND The end of the file (or the end of
of the parent chunk, if given) was
reached before the desired chunk is
found.
VF_NOTSUPPORTED The contents of the RIFF formatted
voice file includes a feature not
supported.
VF_BADPARAMETER An invalid parameter was passed to
the
VF_DOSWRITE A DOS error occured while writing
to a file. The specific error code
is contained in the global DOS
error code variable, _errno, ,
supported in all versions of MSC.
VF_DOSREAD A DOS error occured while reading a
file. See the VF_DOSWRITE error
code presented above.
VF_DOSOPEN A DOS error occured while opening a
file. See the VF_DOSWRITE error
code presented above.
Initializes the API. The application may send out a initialization string to the DCE at this time if desired. The callback function is active through out the session beginning with the RVOpen() call and ending at the RVClose() call.
Note all other API functions except the RVClose() will return an error unless RVOpen() is called first.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVOpen(
unsigned char far *InitString, int (FAR PASCAL *RVCallBack());
Type/Parameter Description
unsigned char far Optional application specific initialization
*InitString; string.
int (FAR PASCAL API callback function. Returns events detected
*RVCallBack() by the DCE. The events may be DTMF tones, call
progress cadences, and quiet determinations.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
This function sets the DCE to the indicated Mode and Baud Rate. This function is used for starting and ending the voice mode. Note that most voice functions (DCE commands) are only valid while the DCE is in the Voice Mode. See page 11 for a discussion of the Voice Mode.
This function assumes that the "DTE Software" has established a working DTE/DCE serial link.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVSetVMBaudRate(
int Mode, int BaudRate);
Type/Parameter Description
int Mode DCE mode to switch to. See Table 1, page 11,
for some possible mode settings. A value of -1
indicates that the API should not change the
mode.
int BaudRate New baud rate. Should be a multiple of 2400.
For example, a value of 16 indicates a baud
rate of 38400. A value of -1 indicates that
the API should not change the baud rate.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Gets the current voice setting - BPS, sample rate, compression method identifier, silence deletion threshold, DTMF/Tone detection setting, and Voice I/O line of the DCE. See page 12 for a discussion of the term BPS.
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVGetCurrentSetting();
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD, and RV_CB_CMID.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Gets the sample rate range, silence deletion range, and DTMF/Tone detection capabilities for each possible BPS supported by the DCE. Silence deletion sensitivity and DTMF/Tone detection capabilities are covered in Rockwell's specification - Voice in the AC Products (Version April, 1992). See page 12 for a discussion of the term BPS.
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVGetBPSRange();
This functions makes use of the RVCallBack() function with the following identifier code: RV_CB_VCI.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Gets all of the possible Compression Method Identifier strings supported by the DCE. The compression method identifier is covered in Rockwell's specification - Voice in the AC Products (Version April, 1992).
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVGetCMIdRange();
This functions makes use of the RVCallBack() function with the following identifier code: RV_CB_CMID.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Gets the voice line attribute for each voice line the DCE supports.
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVGetVLRange();
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VLA.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Sets the Voice mode - BPS, sample rate, silence deletion sensitivity, Voice I/O Line, baud rate, and "DTMF/Tone Detection Mask". This function also returns the resulting DTMF/Tone detection capabilities. The possible sample rates, silence deletion sensitivities, and DTMF/Tone detection depend on the BPS selected. Silence deletion sensitivity and DTMF/Tone detection capabilities are covered in Rockwell's specification - Voice in the AC Products (Version April, 1992). See page 12 for a discussion of the term BPS.
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVSetCurrentSetting(
struct VPS far *VoiceParmSetting, struct VTD far *ToneDetectionMask,
int BaudRate);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD, and RV_CB_BDR.
Type/Parameter Description
struct VPS far If this pointer is not null, the API sets the
*VoiceParmSetting parameters for the Voice Mode. If the pointer
is null, the API does not do any operation
associated with this structure - BPS, sample
rate, silence deletion sensitivity, and Voice
I/O Line. See page 15 for the definition of
the VPS structure.
struct VTD far If this pointer is not null, the API masks out
*ToneDetectionMask some DCE DTMF/Tone detection capabilities. If
the pointer is null, the API does no masking
(enabling and disabling) operations. The API
ignores the VoiceLine member (Voice line
switches while off hook are not allowed). See
page 15 for the definition of the VTD
structure.
int BaudRate New baud rate. Should be a multiple of 2400.
For example, a value of 16 indicates a baud
rate of 38400. A value of -1 indicates that
the API should not change the baud rate.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Allows the "DTE Software" to quickly change the Voice Mode to three possible configurations - the best compression, the worst compression, and someplace in the middle. See page 11 for a discussion of the Voice Mode.
Assumes that the DCE is already in the Voice Mode. Assumes that the "DTE Software" has called the RVGetBPSRange() function to fill an array of VCI information structures.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVSetCurrentMode(
unsigned int Mode,struct VCI far *VoiceCapsInfo, unsigned int VCINumber);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD, and RV_CB_BR.
Type/Parameter Description
unsigned int Mode Three values are allowed - 0, 1, or 2. The
number zero indicates the worst compression
(but still compressed), and the number two
indicates the best compression. The number one
indicates someplace in the middle.
struct VCI far Array of Voice information structures necessary
*VoiceCapsInfo to determine which combination of BPS, sample
rate, and silence deletion is appropriate for
the Mode selected. See page 17 for the
definition of the VCI structure.
unsigned int VCINumber Number of array elements starting at the
VoiceCapsInfo pointer.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Dials a phone number. The API does no processing of the dial string, and the acceptance of special characters, such as @ and !, is determined by the DCE implementation.
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVDial(
unsigned char far *DialNumber)
Type/Parameter Description unsigned char far ASCIIZ dial string. *DialNumber
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Answers the phone.
Assumes that the DCE is already in the Data Mode. See page 11 for a discussion of the different Modes. This function answer the phone, and, optionally, switch to a Voice mode.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVAnswer(
unsigned int WaitLimit, unsigned int Mode, unsigned int BaudRate);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_BDR and RV_CB_CLS.
Type/Parameter Description
unsigned int WaitLimit Maximum time, in seconds, the API will wait, in
the polling mode, before ending the polling
mode and returning an error code. A value of
zero indicates an indefinite wait period. The
"DTE Software" should use the RVStopVoiceIO()
function to terminate the polling mode.
unsigned int Mode DCE mode to switch to. See Table 1, page 11,
for some possible mode settings. If the
VoiceParmSetting pointer is null, the API will
ignore this parameter.
unsigned int BaudRate New baud rate. Should be a multiple of 2400.
For example, a value of 16 indicates a baud
rate of 38400. If the VoiceParmSetting pointer
is null, the API will ignore this parameter.
Return Value:
Zero indicates no immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Checks a list of Voice files for compatible BPS, sample range, and silence deletion sensitivity. Silence deletion sensitivity and DTMF/Tone detection capabilities are covered in Rockwell's specification - Voice in the AC Products (Version April, 1992). See page 12 for a discussion of the term BPS.
Assumes that the DCE is already in the Voice Mode. See page 11 for a discussion of the Voice Mode. This routine also assumes that the files are in the Rockwell RIFF format.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVCheckVoiceFiles(
unsigned char far *VoiceFiles[],
unsigned char far *CMIdString[], unsigned int CMIdSize,
struct VCI far *VoiceCapsInfo, unsigned int VCINumber);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VCF.
Type/Parameter Description
unsigned char far Array of ASCIIZ voice file names pointers for
*VoiceFiles[] the API to check for BPS, and sample rate. The
list is terminated by a null string pointer.
unsigned char far Array of ASCIIZ compression method identifier
*CMIdString[] strings used by the API to check for compatible
compression methods. The list is terminated by
a null string pointer.
unsigned int CMIdSize The API will limit the compression method
identifier ASCIIZ string to this size.
struct VCI far Array of Voice information structures necessary
*VoiceCapsInfo to determine which combination of BPS, sample
rate, and silence deletion is appropriate for
the Mode selected. See page 17 for the
definition of the VCI structure.
unsigned int VCINumber Number of array elements, VCI structures,
pointed to by the VoiceCapsInfo parameter.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Answers the phone and does call discrimination. See page 59 for a description of the call discrimination algorithm
Assumes that the DCE is already in the Data Mode. See page 11 for a discussion of the different Modes. The API will leave the DCE in the Voice mode when the API has made a determination. The "DTE Software" is expected, at this point, to issue the appropriate commands to enter the mode of choice. Currently, this function only uses the Rockwell RIFF file format with ADPCM.
Returns the API determination, via the RVStatus() (see page 37) function, of the nature of the remote station - facsimile, data, voice, unknown or done (implying voice). See Table 7, "Normal Termination Codes", on page 23 for a list of the normal termination result codes. If the station is a voice station, the API will record the voice automatically.
Polling Command. See page 11 for the definition.
int FAR PASCAL RVAnswerCD(
unsigned int WaitLimit,
struct VTD far *ToneDetectionMask,
unsigned int Mode, unsigned int BaudRate,
unsigned int MaximumMessage,
struct VPS far *RxVoiceParmSetting,
unsigned char far * CMIdString, unsigned char far *VoiceFileName,
unsigned char far *InitialOGM,
unsigned char far *ReservedPtr1,unsigned char *ReservedPtr2);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD,and RV_CB_TONE_CD.
Note that the API will use the DTMF/Tone detection capabilities of the DCE in its call discrimination algorithm.
Type/Parameter Description
unsigned int WaitLimit Maximum time, in seconds, the API will wait, in
the polling mode, before ending the polling
mode and returning an error code. A value of
zero indicates an indefinite wait period. The
"DTE Software" should use the RVStopVoiceIO()
function to terminate the polling mode.
struct VTD far If this pointer is not null, the API masks out
*ToneDetectionMask some DCE DTMF/Tone detection capabilities
during the Voice playbacks and record. If the
pointer is null, the API does not change the
DTMF/Tone detection capabilities of the DCE.
See page 15 for the definition of the VTD
structure.
unsigned int Mode DCE voice mode to switch to. See Table 1, page
11, for some possible mode settings
unsigned int BaudRate New baud rate. Should be a multiple of 2400.
For example, a value of 16 indicates a baud
rate of 38400.
unsigned int If the API should record a message, this is the
MaximumMessage maximum message length in seconds.
struct VPS far If this pointer is not null, the API sets the
*RxVoiceParmSetting parameters for the Voice Mode. If the pointer
is null, the API uses the the current voice
parameters in the modem. Information from this
parameter is embedded in the recorded voice
file. See page 15 for the definition of the
VPS structure.
unsigned char far If this parameter is not null and if the API
*CMIdString should record a message, the API will place
this ASCIIZ compression method identifier
string into the RIFF file. The possible
compression methods are DCE specific. The
compression method identifier is covered in
Rockwell's specification - Voice in the AC
Products (Version April, 1992). If this
parameter is null, the API will make a DCE
inquiry and place the identifier string into
the file. Information from this parameter is
embedded in the recorded voice file.
unsigned char far If the API should record a message, the API
*VoiceFileName will use this Voice file name for record. This
parameter is required.
unsigned char far Optional first prompting message. This message
*InitialOGM should be limited to 1.5 seconds. If this
pointer is zero, the API will ignore this
parameter.
unsigned char far The API currently does not use this pointer;
*ReservedPtr1 reserved for future use.
unsigned char far The API currently does not use this pointer;
*ReservedPtr2 reserved for future use.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Playback a voice file to the current Voice I/O line.
Assumes that the DCE is already in the Voice Mode. This function assumes that the files are in the Rockwell RIFF format, and that the Voice Mode settings in the voice file are valid.
Polling Command. See page 11 for the definition.
int RVPlayFile(
struct VTD far *ToneDetectionMask,
unsigned char far *VoiceFileName);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD,and RV_CB_TONE_TX.
Type/Parameter Description
struct VTD far If this pointer is not null, the API masks out
*ToneDetectionMask some DCE DTMF/Tone detection capabilities. If
the pointer is null, the API does not change
the DTMF/Tone detection capabilities of the
DCE. See page 15 for the definition of the VTD
structure.
unsigned char far Voice file name for playback.
*VoiceFileName
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined in future release.
Playback a voice buffer to the current Voice I/O line.
Assumes that the DCE is already in the Voice Mode. Assumes that the voice mode settings in the voice file are valid.
Polling Command. See page 11 for the definition.
int RVPlayBuffer(
struct VPS far *VoiceParmSetting, struct VTD far *ToneDetectionMask,
long Handle, unsigned long BufferLength;
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD, RV_CB_TONE_RX, RV_CB_TONE_TX, RV_CB_LOCK_MEM, and RV_CB_UNLOCK_MEM.
Type/Parameter Description
struct VPS far If this pointer is not null, the API sets the
*VoiceParmSetting parameters for the Voice Mode. If the pointer
is null, the API does no operation. See page
15 for the definition of the VPS structure.
struct VTD far If this pointer is not null, the API masks out
*ToneDetectionMask some DCE DTMF/Tone detection capabilities. If
the pointer is null, the API does not change
the DTMF/Tone detection capabilities of the
DCE. See page 15 for the definition of the VTD
structure.
long Handle Buffer identifier.
unsigned long Length of buffer identified by the parameter
BufferLength used by the buffer management sub functions
within the callback function.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Record a voice file from the current Voice I/O line.
Assumes that the DCE is already in the Voice Mode.
This function assumes that filename is unique. This function will create voice files in the Rockwell RIFF format, and embed Voice Mode settings in the voice file.
Polling Command. See page 11 for the definition.
int RVRecordFile(
struct VPS far *VoiceParmSetting, struct VTD far *ToneDetectionMask,
unsigned char far * CMIdString, unsigned char far *VoiceFileName);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD, RV_CB_TONE_TX, and RV_CB_TONE_RX.
Note that the API will embed most of the VoiceParmSetting data into the Rockwell RIFF file.
Type/Parameter Description
struct VPS far If this pointer is not null, the API sets the
*VoiceParmSetting parameters for the Voice Mode. If the pointer
is null, the API retrieves the necessary
information for the RIFF file from the current
setting of the DCE. See page 15 for the
definition of the VPS structure.
struct VTD far If this pointer is not null, the API masks out
*ToneDetectionMask some DCE DTMF/Tone detection capabilities If
the pointer is null, the API does not change
the DTMF/Tone detection capabilities of the
DCE. See page 15 for the definition of the VTD
structure.
unsigned char far If this parameter is not null and if the API
*CMIdString should record a message, the API will place
this ASCIIZ compression method identifier
string into the RIFF file. The possible
compression methods are DCE specific. The
compression method identifier is covered in
Rockwell's specification - Voice in the AC
Products (Version April, 1992). If this
parameter is null, the API will make a DCE
inquiry and place the identifier string into
the file. Information from this parameter is
embedded in the recorded voice file.
unsigned char far Voice file name for record.
*VoiceFileName
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Record a voice buffer from the current Voice I/O line.
Assumes that the DCE is already in the Voice Mode.
Polling Command. See page 11 for the definition.
int RVRecordBuffer(
struct VPS far *VoiceParmSetting, struct VTD far *ToneDetectionMask,
long Handle, unsigned long BufferLength);
This functions makes use of the RVCallBack() function with the following identifier codes: RV_CB_VPS, RV_CB_VTD, RV_CB_TONE_TX, RV_CB_TONE_RX, RV_CB_LOCK_MEM, and RV_CB_UNLOCK_MEM.
Type/Parameter Description
struct VPS far If this pointer is not null, the API sets the
*VoiceParmSetting parameters for the Voice Mode. If the pointer
is null, the API retrieves the necessary
information from the current setting of the
DCE. See page 15 for the definition of the VPS
structure.
struct VTD far If this pointer is not null, the API masks out
*ToneDetectionMask some DCE DTMF/Tone detection capabilities If
the pointer is null, the API does not change
the DTMF/Tone detection capabilities of the
DCE. See page 15 for the definition of the VTD
structure.
long Handle Buffer identifier.
unsigned long Length of buffer identified by the parameter
BufferLength Handle.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined in the future release.
Polls the API in order to give the API the opportunity to command and to solicit responses from the DCE.
Assumes that the DCE is already in the Voice Mode.
int RVPoll();
Return Value:
None.
Returns status of current polling operation in progress.
Assumes that the DCE is already in the Voice Mode.
int RVStatus();
See section on errors starting on page 23.
Orderly exit from the current Voice I/O activity, returning to the voice command mode or an onhook state.
Assumes that the DCE is already in the Voice Mode.
int RVStopVoiceIO(int StopCode);
Type/Parameter Description
int StopCode Indicates the final state of the modem desired
after the current processing is terminated.
This parameter is currently defined as RV_STOP
or RV_HANGUP. RV_STOP indicates a return to
voice command mode, having no effect if this is
already the current mode. RV_HANGUP indicates
a return to the onhook state regardless of the
currently active state.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of an Immediate Error.
Plays application specific combination of DMTF tones, single and dual tones, with various cadences.
int FAR PASCAL RVPlayTone(
unsigned char far *ToneString);
Type/Parameter Description
unsigned char far Optional application specific initialization
*ToneString string. The API does no processing of the tone
string. Refer to Rockwell's specification -
Voice in the AC Products (Version April, 1992)
for the tone string syntax.
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
De-initializes the API. The callback function declared by the RVOpen() command is no longer valid.
Note: All other API functions except the RVOpen() will return an error after the RVClose()call.
int FAR PASCAL RVClose();
Return Value:
Zero indicates no Immediate Error. Other error codes are to be determined (TBD). See page 12 for the definition of Immediate Error.
Debug functions are designed for use in error detection and diagnosis. They provide an informative display in real time of the inner workings of the API. They may be used in the verification of the functional design produced by the Application Developer for the implementation of the API. It is suggested that these functions become a permanent part of the voice modem module within the End User Application, isolated from production code with preprocessor directives.
The source for these functions is provided to allow custom modification and enhancement. All functions, however, must be minimally defined as empty code blocks to allow successful linkage.
This function allows examination of the processed AT commands sent to the fax modem by directing them to the standard output device (stdout is the destination for the DOS version only). The API will call this function at the appropriate time, passing a pointer to the AT command string written to the COMx port. It is primarily used for debugging and is not intended for use in the deliverable production application.
This function differs from RVShowTxAT() in the origin of the AT command string displayed. RVShowRxAT() will return the AT Command echoed by the DCE (Data Circuit Equipment) and processed by the API, not the AT Command actually received to the modem.
void FAR PASCAL RVShowRxAT(s)
Type/Parameter Description
unsigned char far *s Points to the character string buffer allocated
by the calling function, containing a
processed, NULL terminated AT command string.
Return Value:
No return value.
This function allows examination of the AT commands sent to the modem by directing them to the standard output device (stdout is the destination for the DOS version only). The API will call this function at the appropriate time, passing a pointer to the AT command string to be output in a parameter. It is primarily used during error correction and diagnosis and is not intended for use in the deliverable production application.
void FAR PASCAL RVShowTxAT(s)
Type/Parameter Description
unsigned char far *s Points to the character string buffer allocated
by the calling function, containing a NULL
terminated AT command string.
Return Value:
No return value.
This function is called by the API and is used to produce brief progress messages describing non-fatal error messages at critical intervals in the fax transaction.
The actual format and content of these messages depends on the code created by the Developer. Development of this function is not required but must be minimally defined as an empty function for successful linkage.
void FAR PASCAL RVWarnReport(code, line, fn);
Type/Parameter Description
int code Indicates the error code which describes the
nature of the warning.
int line Indicates the number of the line of code
relative to the source module, from which this
function was called.
unsigned char *fn Points to a character string which contains the
name of the source module, from which this
function was called.
Return Value:
No return value.
This function prints a short report to the default display device, describing the successful transmission/reception of the fax transaction. The format and content of the report will depend on the Application Developer.
void FAR PASCAL RVEndTransReport(code, line, fn,userabort);
Type/Parameter Description
int code Indicates the error code describing the final
status of the fax transaction. Refer to
Appendix A for a list of available error codes.
int line Indicates the number of the line of code
relative to the source module, from which this
function was called.
unsigned char *fn Points to a character string which contains the
name of the source module, from which this
function was called.
int userabort A boolean value where TRUE indicates a
termination due to a user initiated abort.
Return Value:
No return value.
The Session Functions are required in staging the activation of the API by performing system specific initialization, such as that required for the use of a Windows DLL. Though the API does NOT directly call the Session functions defined, it does depend on the successful execution of the functionality specified for each.
The source for these functions is provided for both the DOS and Windows environments to allow custom modification and enhancement. Please refer to the Deliverable section of this document to determine the DOS file name of the module containing the Session Functions.
This function performs the required shut down of the active API session for both the API and associated DLL modules (Windows version only).
This function is NOT called by the API. It is specified here as a description of the example supplied and as a recommendation of the functionality which should be provided in any similar function that is coded by the developer.
unsigned int FAR PASCAL RVCloseSess(void)
Type/Parameter Description void No parameter required.
Return Value:
A non zero value indicates an error has occurred.
This function performs initialization of the API and the initialization specific to the target environment, such as COMx port validity checks and DLL initialization. Please refer to the example source for this function, specific to the Windows and DOS environments.
The second parameter param is reserved for the use by the Developer. The example source uses the param parameter to pass Windows COMx configuration parameters from the Windows application to the API DLL Serial I/O functions. Refer to the Deliverables section of this document to determine the DOS file name of this example and the definition of the MAX_COM_ID constant.
This function is NOT called by the API. It is specified here as a description of the example supplied and as a recommendation of the functionality which should be provided in any similar function that is coded by the developer.
unsigned int FAR PASCAL RVOpenSess(id,param)
Type/Parameter Description
unsigned int id Indicates the COMx port to use for all
subsequent serial I/O, in the range of 0 -
MAX_COM_ID.
long param Optional parameter to be defined by the
developer.
Return Value:
A non zero value indicates an error has occurred.
Timer functions are used to update API internal timers and set the duration of designated state machine events. The default values of most configurable timers need not be adjusted. Certain timers, however, must always be set to control the duration of variable events, such as answering an incoming call.
This function is called by the API during execution of RFPoll to update the API clocks from the system clocks.
void FAR PASCAL RVPollSysTimer(void)
Type/Parameter Description void No parameter required.
Return Value:
None.
This function is called by the API and initializes the API timers.
void FAR PASCAL RVPollSysTimerInit(void)
Type/Parameter Description void No parameter required.
Return Value:
None.
This function is used to update the API internal timers with the amount of time which has passed since the last function call.
The ftime() function, available in all versions of Microsoft C, may be used to obtain the numeric values representing system time, in the fields of a timeb structure. Refer to the Microsoft Run Time Library Reference documentation for more information on the use of the ftime() function. An isochronous IRQ may also be used to detect system clock ticks.
void FAR PASCAL RVUpdateTimers(duration)
Type/Parameter Description
unsigned int duration The quantity in milliseconds which has
transpired since the last call to this
function.
Return Value:
No return value.
This function sets/gets the internal watchdog timers used by the API. The Developer should exercise caution when using this function. For a set/get operation, an array size of WD_NUM ints should be declared in the local data segment. The constant, WD_NUM, is defined in the file "API.H".
Defined Watchdog Timer values:
Timer Index Description
RV_WD_INIT Initialization timeout for trying different
initialization strings at various baud rates.
RV_WD_AT_RESPONSE General timeout for DCE to DTE transactions.
RV_WD_RING_WAIT Ring timeout for receiving a "RING" response
string from the modem during a Receive
Transaction. The API aborts the receive mode
on the expiration of this timeout value . The
timer value is not implemented in current VAPI
RVWD_RING_COUNT Ring timeout for resetting the ring count
during a Receive Transaction. The API resets
the current value for previously detected
"RING" response strings on the expiration of
this timeout value .The timer value is not
implemented in current VAPI
void FAR PASCAL RVWDControl(set, wd)
Type/Parameter Description
int set A non-zero value will set the API watchdog
timer limits to those contained in the wd
parameter. A zero value results in the
transfer of the API's current watchdog timer
limits to the caller's local RAM referenced by
the wd parameter.
unsigned int *wd, (out) Pointer to a block of RAM in the caller's data
segment. The size of this block of RAM is
given by the constant WD_NUM, which is defined
in the file "API.H".
Return Value:
No return value.
Opens the specified RIFF formatted voice file using the access flags contained in the last parameter. If the appropriate flag is included in the dwOpenFlag parameter, the specified file will be created or the existing file truncated to zero bytes.
This function represents the encapsulation of function calls to a lower level API that is identical to the RIFF API specified in the Microsoft Multmedia SDK documentation.
int FAR PASCAL VF_OpenVoice(
register LPVF vf, LPSTR lpszFileName, DWORD dwOpenFlag);
Type/Parameter Description
register LPVF vf A long pointer to a structure used in
maintaining the internal state information of
lower level RIFF functions, and the contents of
the "chunk" data defined in the specification
of the RIFF formatted Microsoft WAVE file. The
memory required for this structure must be
allocated by the calling module and maintained
as long as the associated RIFF formatted voice
file is open. See page 18 for a complete
description of the Rockwell RIFF Formatted
Voice File Structure.
LPSTR lpszFileName A long pointer to the null terminated character
string containing the name of the file to be
opened or created as determined by the contents
of the dwOpenFlags parameter described below.
DWORD dwOpenFlags An unsigned long integer containing DOS file
access codes such as MMIO_READ, MMIO_WRITE,
MMIO_READWRITE, MMIO_DELETE, and MMIO_CREATE.
With the exception of MMIO_CREATE each access
code is mutually exclusive.
Return Value:
Zero indicates no Immediate Error. Any other nonzero value indicates an error. See page 12 for the definition of an Immediate Error. See page 26 for the definition of the .
Reads a specified number of bytes into a previously allocated buffer and returns the actual number of bytes read if successful.
This function represents the encapsulation of function calls to a lower level API that is identical to the RIFF API specified in the Microsoft Multmedia SDK documentation.
int FAR PASCAL VF_ReadVoice(
register LPVF vf, HPSTR pCh, WORD cCh);
Type/Parameter Description
register LPVF vf A long pointer to a structure used in
maintaining the internal state information of
lower level RIFF functions, and the contents of
the "chunk" data defined in the specification
of the RIFF formatted Microsoft WAVE file. The
memory required for this structure must be
allocated by the calling module and maintained
as long as the associated RIFF formatted voice
file is open. See page 18 for a complete
description of the Rockwell RIFF Formatted
Voice File Structure.
HPSTR pCh A long pointer to a block of memory used when
reading the data from the specified RIFF
formatted voice file. For compatibility with
the current Microsoft definition of this
function, HPSTR represents a huge pointer to a
block of memory when the manifest constant
VF_SWIN is defined. The macro HPSTR in all
other cases is identical to LPSTR.
WORD cCh The size in bytes of the memory referenced in
the pCh parameter described above. This
parameter is defined by Microsoft to be LONG to
support the reading of huge blocks of data.
The implementation of this function supplied in
the API uses the standard runtime library
functions to perform all file I/O and
consequently does not support the reading of
data into a buffer which exceeds the number of
bytes in a 64K data segment.
Return Value:
Zero indicates a DOS error occurred in the reading of the file. Since the standard runtime library file I/O functions are used to perform the requested read, the DOS error code which describes this error condition is available using the methods defined in the reference documentation supplied by the compiler vendor.
Positive values indicate a successful read of the file and the actual number of bytes read into the buffer referenced in the pCh parameter.
A negative value indicates a parameter validation error and constitutes an Immediate Error. See page 12 for the definition of an Immediate Error. See page 26 for the definition of the .
Writes the specified number of bytes contained in a previously allocated buffer and returns the actual number of bytes written if successful.
This function represents the encapsulation of function calls to a lower level API that is identical to the RIFF API specified in the Microsoft Multmedia SDK documentation.
int FAR PASCAL VF_WriteVoice(
register LPVF vf, HPSTR pCh, WORD cCh);
Type/Parameter Description
register LPVF vf A long pointer to a structure used in
maintaining the internal state information of
lower level RIFF functions, and the contents of
the "chunk" data defined in the specification
of the RIFF formatted Microsoft WAVE file. The
memory required for this structure must be
allocated by the calling module and maintained
as long as the associated RIFF formatted voice
file is open. See page 18 for a complete
description of the Rockwell RIFF Formatted
Voice File Structure.
HPSTR pCh A long pointer to a block of memory containing
the data to be written to the specified RIFF
formatted voice file. For compatibility with
the current Microsoft definition of this
function, HPSTR represents a huge pointer to a
block of memory when the manifest constant
VF_SWIN is defined. The macro HPSTR in all
other cases is identical to LPSTR.
WORD cCh The number of bytes of memory, referenced in
the pCh parameter described above, to be
written to the specified RIFF file. This
parameter is defined by Microsoft to be LONG to
support the writing of huge blocks of data.
The implementation of this function supplied in
the API uses the standard runtime library
functions to perform all file I/O and
consequently does not support the writing of
data from a buffer which exceeds the number of
bytes in a 64K data segment.
Return Value:
Zero indicates a DOS error occurred in writing to the specified RIFF file. Since the standard runtime library file I/O functions are used to perform the requested write, the DOS error code which describes this error condition is available using the methods defined in the reference documentation supplied by the compiler vendor.
Positive values indicate a successful write to the specified RIFF file and the actual number of bytes written.
A negative value indicates a parameter validation error and constitutes an Immediate Error. See page 12 for the definition of an Immediate Error. See page 26 for the definition of the .
Closes the specified RIFF formatted voice file.
int FAR PASCAL VF_CloseVoice(
register LPVF vf);
Type/Parameter Description
register LPVF vf A long pointer to a structure used in
maintaining the internal state information of
lower level RIFF functions, and the contents of
the "chunk" data defined in the specification
of the RIFF formatted Microsoft WAVE file. The
memory required for this structure must be
allocated by the calling module and maintained
as long as the associated RIFF formatted voice
file is open. See page 18 for a complete
description of the Rockwell RIFF Formatted
Voice File Structure.
Return Value:
Zero indicates no Immediate Error. Any other nonzero value indicates an error. See page 12 for the definition of an Immediate Error. See page 26 for the definition of the .
Note that the following functions do not come in the basic package; special arrangements are necessary before these functions are release in object. Source for the kernel VAPI functions, not including the test harness and developer's functions, always take special arrangements.
The application software must call this function before any of the decompression functions are called - RVDecom2bps(), RVDecom3bps(), and RVDecom4bps(). If the application software switches to another BPS or silence insertion setting, this function must be called again. This function needs to be called only once per setting. This call initializes internal variables inside of the API and these variables are shared between the decompression and compression routines, in fact, RVComInit() makes an RVDecomInit() call. This implies that compression and decompression functions cannot be switched freely, even if they share a common BPS setting, without doing the appropriate initialization function beforehand.
void FAR PASCAL RVDecomInit(
int SetSLFlag, unsigned int bps, unsigned int (far pascal *SLCallBack)());
Type/Parameter Description
int SetSLFlag Indicates whether decompression functions
should look for silence insertion codewords in
the compressed voice data streams. A non-zero
value enables the silence insertion. A zero
value disables silence insertion.
unsigned int bps Number of bits per sample in the compressed
data stream.
unsigned int (far Callback function. Decompression functions
pascal *SLCallBack)() only calls this routine if the parameter
SetSLFlag is enabled.
Return Value:
None.
This function decompresses Rockwell 3 BPS ADPCM codewords into signed 16 bit PCM codewords. The application software must call the RVDecomInit() function before making use of this function in order that the internal variables within the API are properly initialized. Silence insertion is only enabled by the RVDecomInit() function.
Note that the significant bits in the decompressed codeword are in the most significant byte (8 bits) of the 16-bit codeword. This is new for this version; the previous version used the lower 8 bits.
Note that the function accepts compressed codewords in groups of three.
unsigned long PASCAL RVDecom3bps(
unsigned int Qdata0,unsigned int Qdata1,unsigned int Qdata2,
unsigned int far *YnPtr);
Type/Parameter Description
unsigned int Qdata0 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the first of a group of three.
unsigned int Qdata1 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the second of a group of three.
unsigned int Qdata2 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the third of a group of three.
unsigned int far *YnPtr Destination pointer. The application should be
able to accept 16 decompressed codewords for
each function call. Each decompressed codeword
is a signed 16 bit number.
Return Value:
The upper sixteen bits contain the number of decompressed codewords produced. The lower sixteen bits contain the number of compressed data words processed.
If silence insertion is disabled, the values are fixed at 16 codewords produced, and 3 codewords consumed.
If silence insertion is enabled, the decompression function makes use of the callback function to report the number of silence codewords that the application should insert in the data stream. The point of silence insertion is as follows. The application should wait until the decompression function returns with the number of decompressed codewords produced, adjust its buffer pointer to the end of the buffer, and then fill the buffer with the prescribed number of 16 bit binary zero codewords.
This function decompresses Rockwell 4 BPS ADPCM codewords into signed 16 bit PCM codewords. The application software must call the RVDecomInit() function before making use of this function in order that the internal variables within the API is properly initialized. Silence insertion is only enabled by the RVDecomInit() function.
Note that the significant bits in the decompressed codeword are in the most significant byte (8 bits) of the 16-bit codeword. This is new for this version; the previous version used the lower 8 bits.
Note that the function accepts compressed codewords in groups of three.
unsigned long PASCAL RVDecom4bps(
unsigned int Qdata0,unsigned int Qdata1,unsigned int Qdata2,
unsigned int far *YnPtr);
Type/Parameter Description
unsigned int Qdata0 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the first of a group of three.
unsigned int Qdata1 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the second of a group of three.
unsigned int Qdata2 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the third of a group of three.
unsigned int far *YnPtr Destination pointer. The application should be
able to accept 12 decompressed codewords for
each function call. Each decompressed codeword
is a signed 16 bit number.
Return Value:
The upper sixteen bits contain the number of decompressed codewords produced. The lower sixteen bits contain the number of compressed data words processed.
If silence insertion is disabled, the values are fixed at 12 codewords produced, and 3 codewords consumed.
If silence insertion is enabled, the decompression function makes use of the callback function to report the number of silence codewords that the application should insert in the data stream. The point of silence insertion is as follows. The application should wait until the decompression function returns with the number of decompressed codewords produced, adjust its buffer pointer to the end of the buffer, and then fill the buffer with the prescribed number of 16 bit binary zero codewords.
This function decompresses Rockwell 2 BPS ADPCM codewords into signed 16 bit PCM codewords. The application software must call the RVDecomInit() function before making use of this function in order that the internal variables within the API is properly initialized. Silence insertion is only enabled by the RVDecomInit() function.
Note that the significant bits in the decompressed codeword are in the most significant byte (8 bits) of the 16-bit codeword. This is new for this version; the previous version used the lower 8 bits.
Note that the function accepts compressed codewords in groups of three.
unsigned long PASCAL RVDecom2bps(
unsigned int Qdata0,unsigned int Qdata1,unsigned int Qdata2,
unsigned int far *YnPtr);
Type/Parameter Description
unsigned int Qdata0 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the first of a group of three.
unsigned int Qdata1 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the second of a group of three.
unsigned int Qdata2 This function only accepts three sixteen bit
compressed codewords at a time. This parameter
is the third of a group of three.
unsigned int far *YnPtr Destination pointer. The application should be
able to accept 24 decompressed codewords for
each function call. Each decompressed codeword
is a signed 16 bit number.
Return Value:
The upper sixteen bits contain the number of decompressed codewords produced. The lower sixteen bits contain the number of compressed data words processed.
If silence insertion is disabled, the values are fixed at 24 codewords produced, and 3 codewords consumed.
If silence insertion is enabled, the decompression function makes use of the callback function to report the number of silence codewords that the application should insert in the data stream. The point of silence insertion is as follows. The application should wait until the decompression function returns with the number of decompressed codewords produced, adjust its buffer pointer to the end of the buffer, and then fill the buffer with the prescribed number of 16 bit binary zero codewords.
The application software must call this function before any of the decompression functions are called - RVCom2bps(), RVCom3bps(), and RVCom4bps(). If the application software switches to another BPS setting, this function must be called again. This function needs to be called only once per setting. This call initializes internal variables inside of the API and these variables are shared between the decompression and compression routines, in fact, RVComInit() makes an RVDecomInit() call. This implies that compression and decompression functions cannot be switched freely, even if they share a common BPS setting, without doing the appropriate initialization function beforehand.
void FAR PASCAL RVComInit(
unsigned int bps);
Type/Parameter Description
unsigned int bps Number of bits per sample in the decompressed
data stream.
Return Value:
None.
This function compresses signed 16 bit PCM codewords into Rockwell 3 BPS ADPCM codewords. The application software must call the RVComInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function produces compressed codewords in groups of three.
unsigned long PASCAL RVCom3bps(
unsigned int *XnPtr,unsigned int far *YnPtr);
Type/Parameter Description
unsigned int *XnPtr Source pointer. This function accepts 16
decompressed codewords (each codeword is 16
bits) at a time.
unsigned int far *YnPtr Destination pointer. The application should be
able to accept 3 compressed codewords for each
function call (the function will write this
amount). Each compressed codeword is a 16 bit
number.
Return Value:
The upper sixteen bits contain the number of compressed codewords produced. The lower sixteen bits contain the number of decompressed data words processed.
The values are fixed at 3 codewords produced, and 16 codewords consumed.
This function compresses signed 16 bit PCM codewords into Rockwell 4 BPS ADPCM codewords. The application software must call the RVComInit() function before making use of this function in order that the internal variables within the API are properly initialized.
Note that the function produces compressed codewords in groups of three.
unsigned long PASCAL RVCom4bps(
unsigned int *XnPtr,unsigned int far *YnPtr);
Type/Parameter Description
unsigned int *XnPtr Source pointer. This function accepts 12
decompressed codewords (each codeword is 16
bits) at a time.
unsigned int far *YnPtr Destination pointer. The application should be
able to accept 3 compressed codewords for each
function call (the function will write this
amount). Each compressed codeword is a 16 bit
number.
Return Value:
The upper sixteen bits contain the number of compressed codewords produced. The lower sixteen bits contain the number of decompressed data words processed.
The values are fixed at 3 codewords produced, and 12 codewords consumed.
This function compresses signed 16 bit PCM codewords into Rockwell 2 BPS ADPCM codewords. The application software must call the RVComInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function produces compressed codewords in groups of three.
unsigned long PASCAL RVCom2bps(
unsigned int *XnPtr,unsigned int far *YnPtr);
Type/Parameter Description
unsigned int *XnPtr Source pointer. This function accepts 24
decompressed codewords (each codeword is 16
bits) at a time.
unsigned int far *YnPtr Destination pointer. The application should be
able to accept 3 compressed codewords for each
function call (the function will write this
amount). Each compressed codeword is a 16 bit
number.
Return Value:
The upper sixteen bits contain the number of compressed codewords produced. The lower sixteen bits contain the number of decompressed data words processed.
The values are fixed at 3 codewords produced, and 24 codewords consumed.
The following lists the number of multiplies used for each sample of each of the supplied interpolation functions. The larger filter produces better results at the cost of extra compute time.
Function Multiplies per Sample, Multiplies per Sample,
Small Filter Large Filter
RVInterpBuf_144() 16 32
RVInterpBuf_211() 16 32
RVInterpBuf_11025() 16 32
RVInterpBuf_22050() 16 32
12.3.1. RVInterpInit()
The application software must call this function before any of the interpolation functions are called - RVInterpBuf_144(), RVInterpBuf_211(), RVInterpBuf_11025(), and RVInterpBuf_22025(). This function needs to be called only once per setting. This call initializes internal variables inside of the API.
void PASCAL RVInterpInit();
Return Value:
None.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 7200 and converts the data stream into 16 bit PCM codewords sampled at 14400. The application software must call the RVInterpInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function doubles the number of codewords.
unsigned int PASCAL RVInterpBuf_144(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept 2*NPoints
codewords for each function call.
Return Value:
Number of destination codewords (2*NPoints) produced.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 7200 and converts the data stream into 16 bit PCM codewords sampled at 21100. The application software must call the RVInterpInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function triples the number of codewords.
unsigned int PASCAL RVInterpBuf_211(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept 3*NPoints
codewords for each function call.
Return Value:
Number of destination codewords (3*NPoints) produced.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 7200 and converts the data stream into 16 bit PCM codewords sampled at 11025. The application software must call the RVInterpInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function multiplies the number of codewords by a factor of 49/32.
unsigned int PASCAL RVInterpBuf_11025(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept
49*NPoints/32 (round up) codewords for each
function call.
Return Value:
Number of destination codewords (49*NPoints/32 (round up)) produced.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 7200 and converts the data stream into 16 bit PCM codewords sampled at 22050. The application software must call the RVInterpInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function multiplies the number of codewords by a factor of 49/16.
unsigned int PASCAL RVInterpBuf_22050(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept
49*NPoints/16 (round up) codewords for each
function call.
Return Value:
Number of destination codewords (49*NPoints/16 (round up)) produced.
The following lists the number of multiplies used for each sample of each of the supplied decimation functions. The larger filter produces better results at the cost of extra compute time.
Function Multiplies per Sample, Multiplies per Sample,
Small Filter Large Filter
RVDecimBuf_11025() 16 32
RVDecimBuf_22050() 32 64
RVDecimBufHalf22050() 16 16
RVDecimBufQrtr44100() 16 16
12.4.1. RVDecimInit()
The application software must call this function before any of the decimation functions are called - RVDecimBuf_11025(), RVDecimBuf_22025(), and RVDecimBufHalf22025(). This function needs to be called only once per setting. This call initializes internal variables inside of the API.
void PASCAL RVDecimInit();
Return Value:
None.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 11025 and converts the data stream into 16 bit PCM codewords sampled at 7200. The application software must call the RVDecimInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function multiplies the number of codewords by a factor of 32/49.
unsigned int PASCAL RVDecimBuf_11025(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept
32*NPoints/49 (round up) codewords for each
function call.
Return Value:
Number of destination codewords (32*NPoints/49 (round up)) produced.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 22050 and converts the data stream into 16 bit PCM codewords sampled at 7200. The application software must call the RVDecimInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function multiplies the number of codewords by a factor of 32/98.
unsigned int PASCAL RVInterpBuf_22050(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept
32*NPoints/98 (round up) codewords for each
function call.
Return Value:
Number of destination codewords (32*NPoints/98 (round up)) produced.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 22050 and converts the data stream into 16 bit PCM codewords sampled at 11025. The application software must call the RVDecimInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function multiplies the number of codewords by a factor of 1/2.
unsigned int PASCAL RVInterpBufHalf22050(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept NPoints/2
(round up) codewords for each function call.
Return Value:
Number of destination codewords (NPoints/2 (round up)) produced.
This function takes a data stream (buffer full) of signed 16 bit PCM codewords sampled at 44100 and converts the data stream into 16 bit PCM codewords sampled at 11025. The application software must call the RVDecimInit() function before making use of this function in order that the internal variables within the API is properly initialized.
Note that the function multiplies the number of codewords by a factor of 1/4.
unsigned int PASCAL RVInterpBufQrtr44100(
unsigned int far *Spointer; unsigned int far *Dpointer; unsigned int NPoints);
Type/Parameter Description
unsigned int far Source pointer. Each codeword is a 16 bit
*Spointer number.
unsigned int far Destination pointer. Each codeword is a 16 bit
*Dpointer number.
unsigned int NPoints Number of signed 16 bit data points. The
application should be able to accept NPoints/2
(round up) codewords for each function call.
Return Value:
Number of destination codewords (NPoints/4 (round up)) produced.
This function return the version number of the decompression, compression, and sample rate change functions as a group. This function is new for this version; previous version do not contained any equivalent functions.
unsigned int PASCAL RVVerADPCM();
Return Value:
The most significant byte contains the major version, and the least significant byte contains the minor version. Both of this entities are binary; this version starts with 1.0 where "1" (binary 1) is the major version, and "0" ( binary 0) is the minor version.