I am pretty much lost here - I am trying to create a managed c++
wrapper for this dll, so that I can use it from c#/vb.net, however, it
does not conform to any standard style of coding I have seen. It is
almost like it is trying to implement it's own COM interfaces...
below is the header, and a link to the dll+code:
Zip file with header, example, and DLL:
http://www.cdmatech.com/solutions/do...cesdk3_0_c.zip
Again, this dll only have one exported function... anyway, here is
the header and if anyone is willing to give me a clue in how to wrap
this, I would be greatfull.
#ifndef __QSCL_H__
#define __QSCL_H__
/************************************************** ****************************
** qscl
** Copyright (c) 2003 by QUALCOMM, Inc. All Rights Reserved
**
** This is the Qualcomm Speech Codec Library, a collection of
speech
** codecs (encoders and decoders) and associated utilities. A
speech
** codec is an algorithm designed to transform speech-oriented
audio
** between PCM (pulse code modulation) and a compressed format
suitable
** for transmission over a low-bandwidth link.
**
** The speech codecs available in this library are the ones found
on CDMA
** and 3G digital cellular networks.
**
** The interfaces provided in this library follow COM-like
principles
** (Component Object Model) but do not use or require any
Microsoft COM
** libraries or services.
**
** MODULE
** qscl
**
** DESCRIPTION
** This header file defines the classes and interfaces that can
be used
** by applications linking with the library, and provides an
entry point
** method for accessing classes and interfaces.
************************************************** ***************************/
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Common definitions
** ---------------------------------------------------------------------------
************************************************** ***************************/
// Memory-related routines, such as memcmp.
#include <memory.h>
struct QsclGuid
/************************************************** ****************************
** This structure contains a 128-bit globally unique identifier, used
to
** uniquely identify classes and interfaces in this library.
**
** unsigned char data [16]
** This array contains the raw data in the identifier.
************************************************** ***************************/
{
unsigned char data [16];
};
// These macros declare and define a specific GUID. To make sure
GUIDs are
// defined only once, define the preprocessor symbol "QSCLGUID" in
only one of
// your application's modules.
#ifndef QSCLGUID
#define DEFINE_QSCL_GUID(name, b1, b2, b3, b4, b5, b6, b7, b8, b9, \
b10, b11, b12, b13, b14, b15, b16) \
extern "C" const QsclGuid name
#else
#define DEFINE_QSCL_GUID(name, b1, b2, b3, b4, b5, b6, b7, b8, b9, \
b10, b11, b12, b13, b14, b15, b16) \
extern "C" const QsclGuid name = {b1, b2, b3, b4, b5, b6, b7, b8,
b9, \
b10, b11, b12, b13, b14, b15,
b16}
#endif /* QSCLGUID */
inline bool operator == (const QsclGuid &guid1, const QsclGuid &guid2)
/************************************************** ****************************
** This operator tests two globally unique identifiers for equality.
**
** IN const QsclGuid &guid1
** This is one of the globally unique identifiers to test.
**
** IN const QsclGuid &guid2
** This is one of the globally unique identifiers to test.
**
** RETURNS bool
** The value 'true' is returned if the two given identifiers are
equal.
** Otherwise, the value 'false' is returned.
************************************************** ***************************/
{
return (0 == memcmp (&guid1, &guid2, sizeof (QsclGuid)));
}
inline bool operator != (const QsclGuid &guid1, const QsclGuid &guid2)
/************************************************** ****************************
** This operator tests two globally unique identifiers for
inequality.
**
** IN const QsclGuid &guid1
** This is one of the globally unique identifiers to test.
**
** IN const QsclGuid &guid2
** This is one of the globally unique identifiers to test.
**
** RETURNS bool
** The value 'false' is returned if the two given identifiers are
equal.
** Otherwise, the value 'true' is returned.
************************************************** ***************************/
{
return (0 != memcmp (&guid1, &guid2, sizeof (QsclGuid)));
}
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Enumerated types
** ---------------------------------------------------------------------------
************************************************** ***************************/
enum QsclClientOp
/************************************************** ****************************
** This enumerated type lists the different operations the library
can
** request of a client.
************************************************** ***************************/
{
QSCL_CLIENT_INVALID = 0, /* do not use - keep first */
QSCL_CLIENT_READ, /* read data from the client */
QSCL_CLIENT_WRITE, /* write data to the client */
QSCL_CLIENT_SEEK, /* seek to new position in data stream
*/
QSCL_CLIENT_FILE_SIZE, /* return total size of file in bytes */
QSCL_CLIENT_TRUNCATE, /* truncate file at current position */
QSCL_CLIENT_LAST /* do not use - keep last */
};
enum QsclHandleType
/************************************************** ****************************
** This enumerated type lists the different types of data handles
supported
** by this library.
************************************************** ***************************/
{
QSCL_HANDLE_INVALID = 0, /* do not use - keep first */
QSCL_HANDLE_FILE, /* file name */
QSCL_HANDLE_CLIENT, /* client callback */
QSCL_HANDLE_LAST /* do not use - keep last */
};
enum QsclProgressStatus
/************************************************** ****************************
** This enumerated type lists the different status codes that may be
** indicated during a progress callback. A failure status code also
** indicates the background action has stopped.
************************************************** ***************************/
{
QSCL_PROGRESS_STATUS_INVALID = 0, /* do not use - keep first */
QSCL_PROGRESS_STATUS_SUCCESS,
QSCL_PROGRESS_STATUS_FAILURE,
QSCL_PROGRESS_STATUS_LAST /* do not use - keep last */
};
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Callback function types
** ---------------------------------------------------------------------------
************************************************** ***************************/
typedef void (*QsclProgressCallback) (QsclProgressStatus status,
unsigned percent, void
*context);
/************************************************** ****************************
** This callback function can be used to track the progress of a
potentially
** time-consuming operation.
**
** IN QsclProgressStatus status
** This indicates whether or not the conversion is succeeding.
**
** IN unsigned percent
** This is a number from 0 to 100, indicating who much of the
operation
** has been completed, the percent.
**
** INOUT void *context
** This is the context pointer given to the function which
initiated the
** time-consuming operation.
************************************************** ***************************/
typedef unsigned long (*QsclClientCallback) (QsclClientOp op,
unsigned char *buffer,
unsigned long offset,
unsigned long amount,
void *context);
/************************************************** ****************************
** This callback function is used to interface with a client of the
library,
** for transferring data.
**
** IN QsclClientOp op
** This indicates the operation requested of the client.
**
** unsigned char *buffer
** This is the buffer to use, for QSCL_CLIENT_READ and
QSCL_CLIENT_WRITE
** operations.
**
** unsigned long offset
** This is the offset to use, for QSCL_CLIENT_SEEK operations.
**
** unsigned long amount
** This is the number of bytes to read, for QSCL_CLIENT_READ
operations,
** the number of bytes to write, for QSCL_CLIENT_WRITE
operations, or the
** new size of the file, for QSCL_CLIENT_TRUNCATE.
**
** INOUT void *context
** This is the context pointer set in the client handle.
**
** RETURNS unsigned long
** The return value depends on the operation requested. For
** QSCL_CLIENT_READ, it is the actual number of bytes read. For
** QSCL_CLIENT_WRITE, it is the actual number of bytes written.
For
** QSCL_CLIENT_SEEK, it is the actual position of the file
pointer after
** the seek operation.
************************************************** ***************************/
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Structure declarations
** ---------------------------------------------------------------------------
************************************************** ***************************/
struct QsclSpeechInfo
/************************************************** ****************************
** This structure contains information about a speech file, clip, or
codec
** understood by this library.
**
** QsclGuid format
** This identifies the format of the container file for the
speech.
**
** QsclGuid codec
** This identifies the codec used to encode or decode the speech.
**
** unsigned long totalBytes
** This is the size of the speech file or clip, in bytes.
**
** unsigned bytesPerPacket
** This is the size of one encoded packet, in bytes.
**
** unsigned samplesPerBlock
** This is the number of samples that the encoder converts into
an
** encoded packet, or the decoder generated from one encoded
packet.
**
** unsigned samplesPerSecond
** This is the sampling rate used by the codec, in samples per
second.
**
** unsigned bitsPerSample
** This is the number of bits per speech sample.
**
** unsigned encMode
** This is the codec-specific mode parameter to use when encoding
** speech.
************************************************** ***************************/
{
QsclGuid format;
QsclGuid codec;
QsclGuid rateSet;
unsigned long totalBytes;
unsigned bytesPerPacket;
unsigned samplesPerBlock;
unsigned samplesPerSecond;
unsigned bitsPerSample;
unsigned encMode;
};
struct QsclFileHandle
/************************************************** ****************************
** This structure contains information about a file on the computer's
file
** system.
**
** QsclHandleType type
** This should be QSCL_HANDLE_FILE to identify the structure as a
file
** handle.
**
** const char *name
** This is the name of the file on the file system.
************************************************** ***************************/
{
QsclHandleType type; /* must be QSCL_HANDLE_FILE */
const char *name;
};
struct QsclClientHandle
/************************************************** ****************************
** This structure contains information about a data callback
interface to use
** for data transfer.
**
** QsclHandleType type
** This should be QSCL_HANDLE_CLIENT to identify the structure as
a client
** handle.
**
** QsclClientCallback cb;
** This is a pointer to the client's callback function, used to
interface
** with the client.
**
** void *context
** This is the context pointer to give to the client's callback
** function.
************************************************** ***************************/
{
QsclHandleType type; /* must be QSCL_HANDLE_CLIENT */
QsclClientCallback cb;
void *context;
};
union QsclHandle
/************************************************** ****************************
** Tihs union combines together the different types of handles that
may be
** used with the library.
**
** QsclHandleType type
** This identifies the type of the handle.
**
** QsclFileHandle file
** This structure is used if the type of handle is
QSCL_HANDLE_FILE.
**
** QsclClientHandle client
** This structure is used if the type of handle is
QSCL_HANDLE_CLIENT.
************************************************** ***************************/
{
QsclHandleType type;
QsclFileHandle file;
QsclClientHandle client;
};
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Library entry point
** ---------------------------------------------------------------------------
************************************************** ***************************/
extern "C" void *QsclCreateInstance (const QsclGuid &classId,
const QsclGuid &ifId);
/************************************************** ****************************
** This is the entry point function of the library. It provides a
means of
** accessing any class and interface provided by the library. The
** application chooses which class, and which interface to the class,
it
** desires.
**
** IN const QsclGuid &classId
** This is the unique identifier of the class to access.
**
** IN const QsclGuid &ifId
** This is the unique identifier of the interface to access.
**
** RETURNS void *
** A pointer to the requested interface of the requested class is
** returned. If the class or interface requested cannot be
obtained,
** zero is returned.
************************************************** ***************************/
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Public Interfaces
** ---------------------------------------------------------------------------
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_IQsclUnknown,
0x34, 0x10, 0x00, 0x85, 0x8d, 0x6b, 0x4c, 0xd3,
0x83, 0x05, 0xed, 0x56, 0x92, 0x54, 0x3c, 0x9c);
class IQsclUnknown
/************************************************** ****************************
** This is the base class for all interfaces used in this library.
It
** provides basic reference counting services and the ability to
query a
** class for other interfaces.
************************************************** ***************************/
{
public:
virtual unsigned addRef () = 0;
/************************************************** ************************
** This method increments the reference count on the object.
This should
** be done whenever a reference to the object is being given to
another
** entity.
**
** RETURNS unsigned
** The new reference count on the object is returned.
************************************************** ***********************/
virtual unsigned release () = 0;
/************************************************** ************************
** This method decrements the reference count on the object, and
frees
** the object if the count reaches zero. This should be done
whenever a
** reference to the object is no longer going to be used.
**
** RETURNS unsigned
** The new reference count on the object is returned.
************************************************** ***********************/
virtual void *queryInterface (const QsclGuid &ifId) = 0;
/************************************************** ************************
** This method asks a class to return an interface pointer for
one of its
** possibly many interfaces.
**
** IN const QsclGuid &ifId
** This is the unique identifier of the interface requested.
**
** RETURNS void *
** The pointer to the requested interface is returned. If
the object
** does not support the requested interface, zero is
returned.
************************************************** ***********************/
};
DEFINE_QSCL_GUID (ID_IQsclError,
0x52, 0x90, 0x6e, 0x44, 0x65, 0xdc, 0x4d, 0xaa,
0xa3, 0x80, 0x40, 0xc4, 0x79, 0x8d, 0xb0, 0x60);
class IQsclError : public virtual IQsclUnknown
/************************************************** ****************************
** This interface provides a means of determining the cause of a
failure in a
** previous method call on an object.
************************************************** ***************************/
{
public:
virtual bool wasLastError () const = 0;
/************************************************** ************************
** This method returns a flag indicating whether or not the last
** operation performed on the object generated an error.
**
** RETURNS bool
** The value 'true' is returned if the last operation
performed on
** the object generated an error. Otherwise, the value
'false' is
** returned.
************************************************** ***********************/
virtual const char *getLastError () const = 0;
/************************************************** ************************
** This method returns a string identifying the last error to
occur in
** one of the other methods of this interface.
**
** RETURNS const char *
** A string indicating the last error is returned. If no
error
** occurred in the last method call, zero is returned
instead.
************************************************** ***********************/
};
DEFINE_QSCL_GUID (ID_IQsclFile,
0xde, 0x5c, 0x1a, 0xaa, 0xcb, 0xf3, 0x48, 0x76,
0xad, 0x7d, 0xcb, 0xcc, 0xe3, 0xe7, 0x83, 0x92);
class IQsclFile : public virtual IQsclUnknown
/************************************************** ****************************
** This interface provides read and write access to speech files,
performing
** any necessary conversions to read and write speech data between
the format
** used in the file and the format used by the client.
************************************************** ***************************/
{
public:
virtual bool open (const QsclHandle &fileHandle,
bool writeAccess,
const QsclSpeechInfo &fileFormat,
const QsclSpeechInfo &clientFormat) = 0;
/************************************************** ************************
** This method opens the given file handle and prepares to
convert
** between the file format and the desired client format.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** IN bool writeAccess
** If this flag is set, the file is opened for writing, and
any
** previous file with the same name is truncated. Otherwise,
** the file is opened for reading. The file cannot be opened
for
** reading and writing at the same time, due to limitations
with
** certain supported codecs.
**
** IN const QsclSpeechInfo &fileFormat
** This structure identifies the container and codec used
with the
** speech file. If the speech file is opened for reading,
this
** structure also specifies the total size of the input
speech, in
** bytes.
**
** IN const QsclSpeechInfo &clientFormat
** This structure identifies the container and codec used
with the
** speech handled by the client.
**
** RETURNS bool
** The value 'true' is returned if the file is opened
successfully.
** Otherwise, the value 'false' is returned, and the
"getLastError"
** method of the IQsclError interface may be used to
determine the
** cause of the failure.
************************************************** ***********************/
virtual bool close (bool zeroPad) = 0;
/************************************************** ************************
** This method closes the file if it is currently open.
**
** IN bool zeroPad
** This flag indicates what to do with any intermediate
speech
** samples from a previous write, if any. If set to 'true',
one more
** file speech block is generated by padding additional
"silence"
** speech samples onto the end of the intermediate speech
samples,
** converting the samples into one last file speech block,
and
** writing this block to the file just before closing it. If
set to
** 'false', any intermediate speech samples are simply
discarded.
**
** RETURNS bool
** The value 'true' is returned if the file is closed
successfully.
** Otherwise, the value 'false' is returned, and the
"getLastError"
** method of the IQsclError interface may be used to
determine the
** cause of the failure.
************************************************** ***********************/
virtual unsigned long read (unsigned long blocks, void *buffer,
unsigned long *bytes = 0) = 0;
/************************************************** ************************
** This method reads the given number of blocks of speech data
from the
** file, converts it to the client format, and stores it in the
given
** buffer.
**
** If no buffer is given, the method returns the number of client
speech
** blocks that are required to store the given number of
converted file
** speech blocks, rather than actually performing a read.
**
** Note: If the block size of the file and client formats don't
match,
** any extra intermediate speech samples are stored internally
and used
** first for the next read. A seek will clear this internal
buffer.
**
** IN unsigned long blocks
** This is the number of file speech samples to read.
**
** OUT void *buffer
** This points to the buffer in which to store the converted
speech
** samples. If zero, the method calculates and returns the
number of
** client speech blocks that are required to store the given
number
** of converted file speech blocks, rather than actually
performing a
** read.
**
** OUT unsigned long *bytes = 0
** If not zero, this points to a variable to be set to the
total
** number of bytes read into the output buffer. If no buffer
was
** given, this will be the minimum buffer size in bytes
required to
** convert the given number of file speech blocks.
**
** RETURNS unsigned long
** If a buffer is given, the number of converted client
speech blocks
** stored in the buffer is returned. Otherwise, the minimum
buffer
** size required in order to convert the given number of file
speech
** blocks is returned.
**
** Note: If there is a problem reading file speech blocks,
the
** returned block count may not match what the client
expects. The
** client can use the "getLastError" method of the IQsclError
** interface to determine the cause of the failure.
************************************************** ***********************/
virtual unsigned long write (unsigned long blocks, const void
*buffer,
unsigned long *bytes = 0) = 0;
/************************************************** ************************
** This method converts and writes the given number of client
speech
** blocks to the file.
**
** Note: If the block size of the file and client formats don't
match,
** any extra intermediate speech samples are stored internally
and used
** first for the next write. A close will flush this internal
buffer.
**
** IN unsigned long blocks
** This is the number of client speech blocks to convert and
write to
** the file.
**
** IN const void *buffer
** This points to the buffer of client speech blocks to
write.
**
** OUT unsigned long *bytes = 0
** If not 0, this points to a variable to be set to the total
** number of bytes written from the input buffer.
**
** RETURNS unsigned long
** The number of converted client speech blocks written to
the file
** is returned. This may not include intermediate speech
samples
** which did not add up to a whole file speech block in size.
**
** Note: If there is a problem writing file speech blocks,
the
** returned block count may not match what the client
expects. The
** client can use the "getLastError" method of the IQsclError
** interface to determine the cause of the failure.
************************************************** ***********************/
virtual unsigned long seek (unsigned long blockOffset) = 0;
/************************************************** ************************
** This method is only allowed when the file is opened for
reading. It
** moves the file pointer so that subsequent reads will begin
reading
** starting with the given file speech block.
**
** Note: Any intermediate speech samples from a previous read
will be
** cleared by calling this method.
**
** IN unsigned long blockOffset
** This is the block number to which to seek in the file.
**
** RETURNS unsigned long
** The new position of the file pointer, in file speech
blocks, is
** returned. If the new position doesn't match the requested
** position, it means the file does not have enough blocks,
and the
** returned position indicates the block position at the end
of the
** file, one past the last block.
**
** Note: If there is a problem seeking in the file, the
returned file
** pointer position may not match what the client expects.
The
** client can use the "getLastError" method of the IQsclError
** interface to determine the cause of the failure.
************************************************** ***********************/
virtual unsigned long tell () const = 0;
/************************************************** ************************
** This method returns the current file pointer position, in
terms of
** file speech blocks.
**
** Note: Any intermediate speech samples from a previous read or
write
** are not counted in this file pointer position.
**
** RETURNS unsigned long
** The current position of the file pointer is returned.
************************************************** ***********************/
virtual unsigned long getFileSize () const = 0;
/************************************************** ************************
** This method returns the size of the file, in terms of file
speech
** blocks.
**
** RETURNS unsigned long
** The size of the file, in file speech blocks, is returned.
If the
** file handle being used is a client type file handle, the
file size
** cannot be determined, and the return value will be zero.
************************************************** ***********************/
virtual void getInfo (QsclSpeechInfo &info) const = 0;
/************************************************** ************************
** This method returns information about the format of the file
container
** and speech blocks.
**
** OUT QsclSpeechInfo &info
** The given speech information structure is filled with
information
** about the file and its speech.
************************************************** ***********************/
};
DEFINE_QSCL_GUID (ID_IQsclConvertFile,
0x70, 0xfd, 0x01, 0x85, 0x3a, 0xfd, 0x44, 0x1b,
0x80, 0x65, 0x02, 0x88, 0x14, 0xeb, 0xb3, 0x4a);
class IQsclConvertFile : public virtual IQsclUnknown
/************************************************** ****************************
** This interface provides a convenient utility for converting files
between
** different formats. The utility takes care of obtaining the proper
codec
** interfaces, and performing any necessary conversions between
formats.
************************************************** ***************************/
{
public:
virtual bool convertFile (const QsclHandle &inHandle,
const QsclSpeechInfo &inFormat,
const QsclHandle &outHandle,
const QsclSpeechInfo &outFormat,
QsclProgressCallback progressCb = 0,
void *progressContext = 0) = 0;
/************************************************** ************************
** This method begins converting a speech file from one format to
** another. If a progress callback function is given, the
function
** returns immediately, the conversion is done in a separate
thread, and
** the conversion progress is reported to the callback function.
** Otherwise, the method blocks until the conversion is complete,
** converting the speech in the calling thread.
**
** If an encoder is needed to write the output file, and there
are not an
** even multiple of encoder input sample blocks generated from
the input,
** the last encoder input sample block is zero-padded.
**
** IN const QsclHandle &inHandle
** This handle specifies how to obtain the input speech.
**
** IN const QsclSpeechInfo &inFormat
** This structure identifies the container and codec used
with the
** input speech, and the total size of the input speech in
bytes.
**
** IN const QsclHandle &outHandle
** This handle specifies how to produce the output speech.
**
** IN const QsclSpeechInfo &outFormat
** This structure identifies the container and codec to be
used with
** the output speech.
**
** IN QsclProgressCallback progressCb = 0
** If non-zero, this is the function to call back
periodically to
** report progress in converting the speech.
**
** IN void *progressContext = 0
** If a progress callback function is given, this is the
context
** pointer to pass to that function each time it is called.
**
** RETURNS bool
** The value 'true' is returned if the file is converted (or
** conversion is started, in the case of an asynchronous
call)
** successfully. Otherwise, the value 'false' is returned,
and the
** "getLastError" method of the IQsclError interface may be
used to
** determine the cause of the failure.
************************************************** ***********************/
virtual unsigned getProgress () const = 0;
/************************************************** ************************
** This method is used to poll for a progress indicator while a
speech
** file is being converted.
**
** RETURNS unsigned
** A number from 0 to 100 is returned, indicating how far, in
percent
** of the file size, the converter has come converting the
speech
** file.
************************************************** ***********************/
};
DEFINE_QSCL_GUID (ID_IQsclFileOptions,
0x80, 0xce, 0xaa, 0xd1, 0xc4, 0x72, 0x4e, 0x2d,
0x8f, 0xea, 0x7e, 0xe1, 0x2b, 0x14, 0x41, 0x5c);
class IQsclFileOptions : public virtual IQsclUnknown
/************************************************** ****************************
** This interface provides a means to query and change the optional
** information present in a QCP file.
************************************************** ***************************/
{
public:
virtual bool getCnfgChunk (const QsclHandle &fileHandle,
unsigned short &cnfg) const = 0;
/************************************************** ************************
** This method extracts the "cnfg" optional chunk from a QCP
file.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** OUT unsigned short &cnfg
** This is where the 16-bit value in the "cnfg" optional
chunk is
** stored.
**
** RETURNS bool
** The value 'true' is returned if the QCP file had a "cnfg"
optional
** chunk, and the value was returned. Otherwise, the value
'false'
** is returned, indicating there was no "cnfg" chunk or the
file was
** not in QCP format.
************************************************** ***********************/
virtual bool setCnfgChunk (const QsclHandle &fileHandle,
unsigned short cnfg) const = 0;
/************************************************** ************************
** This method sets the "cnfg" optional chunk in the QCP file to
contain
** the given value.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** IN unsigned short cnfg
** This is the value to set in the "cnfg" optional chunk.
**
** RETURNS bool
** The value 'true' is returned if the "cnfg" optional chunk
was
** successfully set. Otherwise, the value 'false' is
returned,
** indicating that the file was not in QCP format.
************************************************** ***********************/
virtual unsigned long getTextChunk (const QsclHandle &fileHandle,
char *buffer,
unsigned long size) const = 0;
/************************************************** ************************
** This method gets the text from the optional "text" chunk in
the QCP
** file.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** INOUT char *buffer
** This is a pointer to the buffer in which to store the text
from
** the "text" optional chunk. If zero, it indicates that
rather than
** extracting the text, the client wishes to know the size of
the
** text in the chunk. No "null" terminator character is
appended to
** the string, unless it was already present in the "text"
chunk.
**
** IN unsigned long size
** This indicates the number of bytes allocated by the client
for the
** buffer passed in, if the buffer pointer is not zero. If
the
** "text" chunk in the file has fewer bytes than this size,
the
** extra bytes in the given buffer are not used. If the
chunk has
** more bytes than this size, only the given number of bytes
are
** copied from the chunk.
**
** RETURNS unsigned long
** If the given buffer pointer was zero, the total number of
bytes in
** the "text" optional chunk is returned. This may be zero
if the
** "text" chunk is empty, if the "text" chunk is not present
in the
** file, or if the file is not a QCP file. If the given
buffer
** pointer is not zero, the total number of bytes copied from
the
** "text" optional chunk is returned. This may be zero if
the "text"
** chunk is empty, if there is no "text" chunk in the file,
or if the
** file is not a QCP file.
************************************************** ***********************/
virtual bool setTextChunk (const QsclHandle &fileHandle,
const char *buffer,
unsigned long size) const = 0;
/************************************************** ************************
** This method copies the given text into the "text" optional
chunk in
** the QCP file, replacing any text that was in the chunk
previously.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** IN const char *buffer
** This points to the buffer of characters to copy into the
"text"
** chunk in the file.
**
** IN unsigned long size
** This is the number of characters to copy into the "text"
chunk in
** the file.
**
** RETURNS bool
** The value 'true' is returned if the file is a QCP file and
the
** given text is stored in the "text" chunk successfully.
Otherwise,
** the value 'false' is returned, indicating that the file is
not a
** QCP file.
************************************************** ***********************/
virtual bool getLablChunk (const QsclHandle &fileHandle,
char *buffer, unsigned long size) const
= 0;
/************************************************** ************************
** This method gets the text from the optional "labl" chunk in
the QCP
** file. The QCP file format specification says this chunk
contains
** exactly 48 bytes of text. Therefore, the client should
provide a
** buffer at least this size to prevent data from being
truncated.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** INOUT char *buffer
** This is a pointer to the buffer in which to store the text
from
** the "labl" optional chunk.
**
** IN unsigned long size
** This indicates the number of bytes allocated by the client
for the
** buffer passed in. If fewer than 48 bytes are allocated,
the data
** copied from the "labl" chunk will be truncated.
**
** RETURNS bool
** The value 'true' is returned if the file is a QCP file
with a
** "labl" optional chunk, and the data from that chunk was
copied to
** the client's buffer.
************************************************** ***********************/
virtual bool setLablChunk (const QsclHandle &fileHandle,
const char *buffer,
unsigned long size) const = 0;
/************************************************** ************************
** This method copies the given text into the "labl" optional
chunk in
** the QCP file, replacing any text that was in the chunk
previously.
**
** IN const QsclHandle &fileHandle
** This handle specifies how to access the speech file.
**
** IN const char *buffer
** This points to the buffer of characters to copy into the
"labl"
** chunk in the file.
**
** IN unsigned long size
** This is the number of characters to copy into the "labl"
chunk in
** the file. If less than 48, the number of bytes specified
in the
** QCP file format specification, the remainder of the "labl"
data
** area is filled with "null" characters. If more than 48,
only the
** first 48 characters are copied into the "labl" chunk.
**
** RETURNS bool
** The value 'true' is returned if the file is a QCP file and
the
** given text is stored in the "labl" chunk successfully.
Otherwise,
** the value 'false' is returned, indicating that the file is
not a
** QCP file.
************************************************** ***********************/
};
DEFINE_QSCL_GUID (ID_IQsclCodec,
0xe6, 0xe9, 0x51, 0x3d, 0x46, 0xc3, 0x42, 0x28,
0xb2, 0x66, 0xb8, 0xe7, 0x98, 0x66, 0x5f, 0xec);
class IQsclCodec : public virtual IQsclUnknown
/************************************************** ****************************
** This interface provides access to one of the supported speech
codecs in
** this library, independent of any file container format.
************************************************** ***************************/
{
public:
virtual bool configure (const QsclGuid &rateSetId,
unsigned mode) = 0;
/************************************************** ************************
** This method configures the object to use the given rate set
and mode,
** and sets it up to either encode or decode speech.
**
** IN const QsclGuid &rateSetId
** This is the unique identifier of the rate set to use.
**
** IN unsigned mode
** This is a codec-specific configuration parameter, which
typically
** selects between different alternate encoding algorithms.
**
** RETURNS bool
** The value 'true' is returned if the codec was successfully
** configured. Otherwise, the value 'false' is returned, in
which
** case the "getLastError" method of the IQsclError interface
may be
** used to determine the cause of the failure.
************************************************** ***********************/
virtual void getInfo (QsclSpeechInfo &decodeFormat,
QsclSpeechInfo &encodeFormat) const = 0;
/************************************************** ************************
** This method returns information about the encode and decode
formats of
** the configured codec. The codec must be configured by calling
the
** "configure" method before this method can be used.
**
** OUT QsclSpeechInfo &decodeFormat
** The information about the format of decoded speech is
stored here.
**
** OUT QsclSpeechInfo &encodeFormat
** The information about the format of encoded speech is
stored here.
************************************************** ***********************/
virtual unsigned getRateSetInfo (unsigned char rate) const = 0;
/************************************************** ************************
** This method returns the number of bytes that are necessary to
store
** the data portion of a speech block with the given rate header
byte.
**
** IN unsigned char rate
** This is the rate header byte of the speech block type in
** question.
**
** RETURNS unsigned
** The number of bytes that are necessary to store the data
portion
** of a speech block with the given rate header byte is
returned. If
** the codec does not define any meaning to the given rate
byte, the
** return value may be zero.
************************************************** ***********************/
virtual const char *getName () const = 0;
/************************************************** ************************
** This method returns the name of the codec.
**
** RETURNS const char *
** The name of the codec is returned.
************************************************** ***********************/
virtual unsigned getVersion () const = 0;
/************************************************** ************************
** This method returns the version number of the codec.
**
** RETURNS unsigned
** The version number of the codec is returned.
************************************************** ***********************/
virtual unsigned getAvgBitrate () const = 0;
/************************************************** ************************
** This method returns the average bitrate of the codec's
encoder, in
** bits per second.
**
** RETURNS unsigned
** The average bitrate of the codec's encoder, in bits per
second, is
** returned.
************************************************** ***********************/
virtual unsigned long convert (void *out, const void *in,
unsigned long blocks, bool encode,
unsigned long *encBytes = 0) = 0;
/************************************************** ************************
** This method uses the codec to encode or decode the given
number of
** blocks of input speech.
**
** OUT void *out
** This points to the buffer in which to store output speech
blocks.
** The client must allocate enough memory to store as many
speech
** blocks as might be generated by the call, otherwise this
method
** may write past the end of the buffer, corrupting memory.
Since
** intermediate speech samples may be added into the
conversion step
** at any point, the client should allocate one extra output
block in
** case those intermediate speech samples added to the new
samples
** add up to one more output block.
**
** IN const void *in
** This points to the buffer containing the input speech
blocks.
**
** IN unsigned long blocks
** This is the number of input speech blocks to be converted.
**
** IN bool encode
** Set this to 'true' to encode speech. Otherwise, set this
to
** 'false' to decode speech.
**
** OUT unsigned long *encBytes = 0
** If non-zero, this points to a variable to set to the total
number
** of encoded speech bytes decoded or encoded. If decoding
speech,
** this is the number of bytes of input used. If encoding
speech,
** this is the number of bytes of output generated.
**
** RETURNS unsigned long
** The number of output speech blocks converted is returned.
If
** fewer blocks are converted than are expected, the client
can call
** the "getLastError" method of the IQsclError interface to
determine
** the cause of the failure.
**
** Note: there may be some left over intermediate speech
samples
** which do not add up to a whole output speech block. In
this case,
** these samples will remain in the object until the next
convert
** call, at which time they will be added in front of the
next input
** blocks to be converted. Intermediate samples are also
cleared out
** whenever the codec is configured.
************************************************** ***********************/
};
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Public Classes
** ---------------------------------------------------------------------------
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_QsclFile,
0x44, 0x60, 0x36, 0x63, 0xb4, 0xc7, 0x48, 0x82,
0xb3, 0x54, 0x41, 0x8d, 0xb8, 0x81, 0x0c, 0xf5);
/************************************************** ****************************
** This class implements the IQsclFile, IQsclConvertFile,
IQsclFileOptions,
** and IQsclError interfaces. It represents a file, with possible
container
** structure, containing speech blocks in one of the supported
formats.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_QsclCodecPcm,
0x19, 0xdd, 0xf9, 0x18, 0xac, 0xe0, 0x43, 0x05,
0x98, 0xef, 0x2c, 0x6c, 0xa6, 0xc8, 0xb6, 0x14);
/************************************************** ****************************
** This class implements the IQsclCodec and IQsclError interfaces.
It
** represents a Pulse code modulation codec object - see
"samplesPerSecond"
** and "bitsPerSample" in QsclSpeechInfo for codec-specific
parameters.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_QsclCodecUlaw,
0x95, 0xb9, 0x1c, 0x42, 0x1f, 0x14, 0x42, 0x40,
0x97, 0xa1, 0x04, 0x5b, 0xdb, 0x08, 0x84, 0xf8);
/************************************************** ****************************
** This class implements the IQsclCodec and IQsclError interfaces.
It
** represents a G.711 (mu-law) codec object - see "samplesPerSecond"
in
** QsclSpeechInfo for codec-specific parameters.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_QsclCodecQcelp,
0x41, 0x6d, 0x7f, 0x5e, 0x15, 0xb1, 0xd0, 0x11,
0xba, 0x91, 0x00, 0x80, 0x5f, 0xb4, 0xb9, 0x7e);
/************************************************** ****************************
** This class implements the IQsclCodec and IQsclError interfaces.
It
** represents an IS-733 Qualcomm PureVoice 13K speech codec object.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_QsclCodecQcelpSmartRate,
0x42, 0x6d, 0x7f, 0x5e, 0x15, 0xb1, 0xd0, 0x11,
0xba, 0x91, 0x00, 0x80, 0x5f, 0xb4, 0xb9, 0x7e);
/************************************************** ****************************
** This class implements the IQsclCodec and IQsclError interfaces.
It
** represents an IS-733 Qualcomm PureVoice 13K speech codec object,
in
** reduced rate mode (SmartRate)
************************************************** ***************************/
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Supported file formats
** ---------------------------------------------------------------------------
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_FormatRaw,
0xd8, 0xa6, 0x72, 0xe4, 0x90, 0xb8, 0x4c, 0x07,
0x8c, 0x68, 0xc4, 0xe0, 0xc2, 0x82, 0xd8, 0xab);
/************************************************** ****************************
** Raw file format - no header information
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_FormatWav,
0xaa, 0x65, 0x63, 0x17, 0xf8, 0x45, 0x41, 0x1c,
0xbe, 0x87, 0x65, 0x4f, 0x54, 0xe9, 0xf4, 0x57);
/************************************************** ****************************
** Microsoft Waveform file format
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_FormatQcp,
0xd8, 0xa5, 0x42, 0xb9, 0xce, 0xa4, 0x4b, 0x19,
0x83, 0x14, 0x2a, 0x08, 0xc5, 0xd3, 0xeb, 0x7b);
/************************************************** ****************************
** Qualcomm PureVoice file format
************************************************** ***************************/
/************************************************** ****************************
** ---------------------------------------------------------------------------
** Supported speech codec rate sets
** ---------------------------------------------------------------------------
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateVariable,
0x9f, 0x4e, 0xf9, 0x4e, 0xa3, 0xd4, 0x4d, 0x09,
0xbe, 0xff, 0x16, 0x5a, 0xaf, 0x6f, 0xef, 0x47);
/************************************************** ****************************
** Variable rate - each packet has a variable length, and is preceded
by a
** "rate byte", or header byte identifying which codec rate or mode
applies
** to the packet. The format of the "rate byte" depends on the
codec.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateHalfMax,
0x6c, 0xac, 0x63, 0xc5, 0xd8, 0x3f, 0x40, 0x6d,
0x96, 0x98, 0xdc, 0x69, 0xfa, 0x7b, 0x78, 0xba);
/************************************************** ****************************
** Half rate max - this is the same as variable rate, except the
maximum rate
** is limited to what the codec defines as "half rate". This is only
valid
** for certain types of codec.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateFixedFull,
0xc0, 0x1d, 0x28, 0xc8, 0x9e, 0x6d, 0x43, 0x9c,
0xa4, 0x1f, 0x6b, 0x71, 0xb1, 0x15, 0x55, 0x58);
/************************************************** ****************************
** Fixed full rate - each packet has a fixed length, and the codec is
locked
** at its maximum rate or mode. There is no "rate byte" header.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateFixedHalf,
0x04, 0x79, 0x19, 0xc9, 0x6e, 0x07, 0x41, 0xe1,
0xa1, 0x10, 0xc1, 0x26, 0xdb, 0x33, 0x42, 0x72);
/************************************************** ****************************
** Fixed half rate - each packet has a fixed length, and the codec is
locked
** at what it defines as "half rate". This is only valid for certain
types
** of codec. There is no "rate byte" header.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateFixedFullWithHeader,
0x9e, 0x71, 0xa4, 0xfb, 0xe1, 0x9c, 0x48, 0x33,
0x82, 0x6c, 0x5c, 0x58, 0x4f, 0x78, 0x4d, 0xf0);
/************************************************** ****************************
** Fixed full rate, with header - each packet has a fixed length, and
the
** codec is locked at its maximum rate or mode. In addition, each
packet is
** preceded by a "rate byte", as in variable rate. Since the rate is
locked,
** this "rate byte" is the same for each packet.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateFixedHalfWithHeader,
0x54, 0x43, 0xb7, 0x86, 0x4d, 0xdd, 0x4a, 0xbe,
0x8a, 0x3c, 0xe5, 0x52, 0x5c, 0xcc, 0x0c, 0xb4);
/************************************************** ****************************
** Fixed half rate, with header - each packet has a fixed length, and
the
** codec is locked at what it defines as "half rate". This is only
valid for
** certain types of codec. In addition, each packet is preceded by a
"rate
** byte", as in variable rate. Since the rate is locked, this "rate
byte" is
** the same for each packet.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateVariablePadded,
0xac, 0xfe, 0x2b, 0xb4, 0xf1, 0xe3, 0x43, 0x70,
0x9b, 0xc5, 0xd3, 0x32, 0x39, 0xba, 0x4f, 0x3f);
/************************************************** ****************************
** Variable rate, padded - this is the same as variable rate, except
each
** packet has a fixed length, set to the length necessary to store a
packet
** of the maximum bit rate. Any unused bytes in a packet are
zero-filled.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateHalfMaxPadded,
0x99, 0x4a, 0xf0, 0x66, 0x66, 0x4d, 0x41, 0x30,
0xa2, 0x8f, 0x36, 0x22, 0xdc, 0x33, 0x12, 0xb6);
/************************************************** ****************************
** Half rate max, padded - this is the same as half rate max, except
each
** packet has a fixed length, set to the length necessary to store a
packet
** at "half rate". Any unused bytes in a packet are zero-filled.
************************************************** ***************************/
DEFINE_QSCL_GUID (ID_RateNative,
0x6a, 0xe2, 0xff, 0x26, 0x8f, 0xbd, 0x4f, 0x09,
0x84, 0xf9, 0x3f, 0x4e, 0x8b, 0x9b, 0x9e, 0x0b);
/************************************************** ****************************
** Codec-native format - typically this is variable rate, zero-padded
to the
** maximum rate, with the rate in a 2-byte word rather than a byte.
************************************************** ***************************/
#endif /* __QSCL_H__ */
