Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

sound.h

Go to the documentation of this file.
00001 /*
00002  * sound.h
00003  *
00004  * Sound interface class.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
00025  * All Rights Reserved.
00026  *
00027  * Contributor(s): ______________________________________.
00028  *
00029  * $Log: sound.h,v $
00030  * Revision 1.31  2004/11/01 23:16:59  ykiryanov
00031  * Added macro declaring sound plugin to be static for BeOS
00032  *
00033  * Revision 1.30  2003/12/28 02:03:18  csoutheren
00034  * Fixed problem with GetLastReadCount/GetLastWriteCount  on Windows sound devices
00035  *
00036  * Revision 1.29  2003/11/18 10:50:26  csoutheren
00037  * Changed name of Windows sound device
00038  *
00039  * Revision 1.28  2003/11/14 05:59:09  csoutheren
00040  * Added Read function, thanks to Derek Smithies
00041  *
00042  * Revision 1.27  2003/11/12 10:25:41  csoutheren
00043  * Changes to allow operation of static plugins under Windows
00044  *
00045  * Revision 1.26  2003/11/12 05:18:04  csoutheren
00046  * Added more backwards compatibility functions for PSoundChannel
00047  *
00048  * Revision 1.25  2003/11/12 04:33:32  csoutheren
00049  * Fixed problem with static linking of sound plugins
00050  * Fixed problem with Windows sound driver
00051  *
00052  * Revision 1.24  2003/11/12 03:29:51  csoutheren
00053  * Initial version of plugin code from Snark of GnomeMeeting with changes
00054  *    by Craig Southeren of Post Increment
00055  *
00056  * Revision 1.23.2.2  2003/10/13 02:42:39  dereksmithies
00057  * Add additional functions, so plugins work better.
00058  *
00059  * Revision 1.23.2.1  2003/10/07 03:02:28  csoutheren
00060  * Initial checkin of pwlib code to do plugins.
00061  * Modified from original code and concept provided by Snark of Gnomemeeting
00062  *
00063  * Revision 1.23  2003/09/17 05:41:59  csoutheren
00064  * Removed recursive includes
00065  *
00066  * Revision 1.22  2003/09/17 01:18:02  csoutheren
00067  * Removed recursive include file system and removed all references
00068  * to deprecated coooperative threading support
00069  *
00070  * Revision 1.21  2002/09/16 01:08:59  robertj
00071  * Added #define so can select if #pragma interface/implementation is used on
00072  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00073  *
00074  * Revision 1.20  2002/02/08 09:58:44  robertj
00075  * Slight adjustment to API and documentation for volume functions.
00076  *
00077  * Revision 1.19  2002/02/07 20:57:21  dereks
00078  * add SetVolume and GetVolume methods to PSoundChannel
00079  *
00080  * Revision 1.18  2001/05/22 12:49:32  robertj
00081  * Did some seriously wierd rewrite of platform headers to eliminate the
00082  *   stupid GNU compiler warning about braces not matching.
00083  *
00084  * Revision 1.17  2001/02/07 03:33:43  craigs
00085  * Added functions to get sound channel parameters
00086  *
00087  * Revision 1.16  2000/03/04 10:15:32  robertj
00088  * Added simple play functions for sound files.
00089  *
00090  * Revision 1.15  1999/05/28 14:04:10  robertj
00091  * Added function to get default audio device.
00092  *
00093  * Revision 1.14  1999/03/09 02:59:51  robertj
00094  * Changed comments to doc++ compatible documentation.
00095  *
00096  * Revision 1.13  1999/02/22 10:15:14  robertj
00097  * Sound driver interface implementation to Linux OSS specification.
00098  *
00099  * Revision 1.12  1999/02/16 06:02:27  robertj
00100  * Major implementation to Linux OSS model
00101  *
00102  * Revision 1.11  1998/09/23 06:21:27  robertj
00103  * Added open source copyright license.
00104  *
00105  * Revision 1.10  1995/06/17 11:13:26  robertj
00106  * Documentation update.
00107  *
00108  * Revision 1.9  1995/03/14 12:42:40  robertj
00109  * Updated documentation to use HTML codes.
00110  *
00111  * Revision 1.8  1995/01/16  09:42:05  robertj
00112  * Documentation.
00113  *
00114  * Revision 1.7  1994/08/23  11:32:52  robertj
00115  * Oops
00116  *
00117  * Revision 1.6  1994/08/22  00:46:48  robertj
00118  * Added pragma fro GNU C++ compiler.
00119  *
00120  * Revision 1.5  1994/06/25  11:55:15  robertj
00121  * Unix version synchronisation.
00122  *
00123  * Revision 1.4  1994/01/03  04:42:23  robertj
00124  * Mass changes to common container classes and interactors etc etc etc.
00125  *
00126  * Revision 1.3  1993/09/29  03:06:30  robertj
00127  * Added unix compatibility to Beep()
00128  *
00129  * Revision 1.2  1993/07/14  12:49:16  robertj
00130  * Fixed RCS keywords.
00131  *
00132  */
00133 
00134 
00135 #ifndef _PSOUND
00136 #define _PSOUND
00137 
00138 #ifdef P_USE_PRAGMA
00139 #pragma interface
00140 #endif
00141 
00142 #include <ptlib/pluginmgr.h>
00143 
00144 #if defined(_WIN32)
00145 PWLIB_STATIC_LOAD_PLUGIN(PSoundChannel_WindowsMultimedia);
00146 #elif defined(__BEOS__)
00147 PWLIB_STATIC_LOAD_PLUGIN(PSoundChannelBeOS);
00148 #endif
00149 
00150 
00158 class PSound : public PBYTEArray
00159 {
00160   PCLASSINFO(PSound, PBYTEArray);
00161 
00162   public:
00171     PSound(
00172       unsigned numChannels = 1,    
00173       unsigned sampleRate = 8000,  
00174       unsigned bitsPerSample = 16, 
00175       PINDEX   bufferSize = 0,     
00176       const BYTE * data = NULL     
00177     );
00178 
00181     PSound(
00182       const PFilePath & filename   
00183     );
00184 
00187     PSound & operator=(
00188       const PBYTEArray & data  // New data for sound
00189     );
00191 
00203     BOOL Load(
00204       const PFilePath & filename   
00205     );
00206 
00213     BOOL Save(
00214       const PFilePath & filename   // Sound file to load.
00215     );
00217 
00220 
00221     BOOL Play();
00222 
00226     void SetFormat(
00227       unsigned numChannels,   // Number of channels eg mono/stereo
00228       unsigned sampleRate,    
00229       unsigned bitsPerSample  
00230     );
00231 
00235     unsigned GetEncoding()   const { return encoding; }
00236 
00238     unsigned GetChannels()   const { return numChannels; }
00239 
00241     unsigned GetSampleRate() const { return sampleRate; }
00242 
00244     unsigned GetSampleSize() const { return sampleSize; }
00245 
00247     DWORD    GetErrorCode()  const { return dwLastError; }
00248 
00250     PINDEX   GetFormatInfoSize()  const { return formatInfo.GetSize(); }
00251 
00253     const void * GetFormatInfoData() const { return (const BYTE *)formatInfo; }
00255 
00266     static BOOL PlayFile(
00267       const PFilePath & file, 
00268       BOOL wait = TRUE        
00269     );
00270 
00272     static void Beep();
00274 
00275   protected:
00277     unsigned   encoding;      
00279     unsigned   numChannels;   
00281     unsigned   sampleRate;    
00283     unsigned   sampleSize;    
00285     DWORD      dwLastError;   
00287     PBYTEArray formatInfo;    
00288 };
00289 
00290 
00321 class PSoundChannel : public PChannel
00322 {
00323   PCLASSINFO(PSoundChannel, PChannel);
00324 
00325   public:
00328     enum Directions {
00329       Recorder,
00330       Player
00331     };
00332 
00334     PSoundChannel();
00335 
00339     PSoundChannel(
00340       const PString & device,       
00341       Directions dir,               
00342       unsigned numChannels = 1,     
00343       unsigned sampleRate = 8000,   
00344       unsigned bitsPerSample = 16   
00345     );
00346     // 
00347 
00348     virtual ~PSoundChannel();
00349     // Destroy and close the sound driver
00351 
00357     static PStringList GetDriverNames(PPluginManager * pluginMgr = NULL);
00358 
00362     static PStringList GetDeviceNames(
00363          const PString &driverName,
00364          const PSoundChannel::Directions,
00365          PPluginManager * pluginMgr = NULL
00366     );
00367 
00371     static PSoundChannel *CreateChannel (
00372       const PString &driverName,
00373       PPluginManager * pluginMgr = NULL
00374     );
00375 
00379     static PSoundChannel * CreateOpenedChannel(
00380       const PString & driverName,
00381       const PString & deviceName,
00382       const PSoundChannel::Directions,
00383       unsigned numChannels = 1,
00384       unsigned sampleRate = 8000,
00385       unsigned bitsPerSample = 16
00386     );
00387 
00396     static PString GetDefaultDevice(
00397       Directions dir    // Sound I/O direction
00398     );
00399 
00408     static PStringList GetDeviceNames(
00409       Directions dir    // Sound I/O direction
00410     );
00411 
00418     virtual BOOL Open(
00419       const PString & device,       
00420       Directions dir,               
00421       unsigned numChannels = 1,     
00422       unsigned sampleRate = 8000,   
00423       unsigned bitsPerSample = 16   
00424     );
00425 
00431     virtual BOOL IsOpen() const
00432       { return (baseChannel == NULL) ? FALSE : baseChannel->PChannel::IsOpen(); }
00433 
00439     virtual int GetHandle() const
00440       { return (baseChannel == NULL) ? -1 : baseChannel->PChannel::GetHandle(); }
00441 
00447     virtual BOOL Abort()
00448     { return (baseChannel == NULL) ? FALSE : baseChannel->Abort(); }
00450 
00462     virtual BOOL SetFormat(
00463       unsigned numChannels = 1,     
00464       unsigned sampleRate = 8000,   
00465       unsigned bitsPerSample = 16   
00466     )
00467     { return (baseChannel == NULL) ? FALSE : baseChannel->SetFormat(numChannels, sampleRate, bitsPerSample); }
00468 
00470     virtual unsigned GetChannels()   const
00471     { return (baseChannel == NULL) ? 0 : baseChannel->GetChannels(); }
00472 
00474     virtual unsigned GetSampleRate() const
00475     { return (baseChannel == NULL) ? 0 : baseChannel->GetSampleRate(); }
00476 
00478     virtual unsigned GetSampleSize() const 
00479     { return (baseChannel == NULL) ? 0 : baseChannel->GetSampleSize(); }
00480 
00489     virtual BOOL SetBuffers(
00490       PINDEX size,      
00491       PINDEX count = 2  
00492     )
00493     { return (baseChannel == NULL) ? FALSE : baseChannel->SetBuffers(size, count); }
00494 
00500     virtual BOOL GetBuffers(
00501       PINDEX & size,    // Size of each buffer
00502       PINDEX & count    // Number of buffers
00503     )
00504     { return (baseChannel == NULL) ? FALSE : baseChannel->GetBuffers(size, count); }
00505 
00506     enum {
00507       MaxVolume = 100
00508     };
00509 
00516     virtual BOOL SetVolume(
00517       unsigned volume   
00518     )
00519     { return (baseChannel == NULL) ? FALSE : baseChannel->SetVolume(volume); }
00520 
00527     virtual BOOL GetVolume(
00528       unsigned & volume   
00529     )
00530     { return (baseChannel == NULL) ? FALSE : baseChannel->GetVolume(volume); }
00532 
00535 
00547      virtual BOOL Write(const void * buf, PINDEX len)
00548       { return (baseChannel == NULL) ? FALSE : baseChannel->Write(buf, len); }
00549 
00550     PINDEX GetLastWriteCount() const
00551     { return (baseChannel == NULL) ? lastWriteCount : baseChannel->GetLastWriteCount(); }
00552 
00569     virtual BOOL PlaySound(
00570       const PSound & sound,   
00571       BOOL wait = TRUE        
00572     )
00573     { return (baseChannel == NULL) ? FALSE : baseChannel->PlaySound(sound, wait); }
00589     virtual BOOL PlayFile(
00590       const PFilePath & file, 
00591       BOOL wait = TRUE        
00592     )
00593     { return (baseChannel == NULL) ? FALSE : baseChannel->PlayFile(file, wait); }
00594 
00601     virtual BOOL HasPlayCompleted()
00602     { return (baseChannel == NULL) ? FALSE : baseChannel->HasPlayCompleted(); }
00603 
00610     virtual BOOL WaitForPlayCompletion() 
00611     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForPlayCompletion(); }
00612 
00614 
00629     virtual BOOL Read(
00630       void * buf,   
00631       PINDEX len    
00632     )
00633     { return (baseChannel == NULL) ? FALSE : baseChannel->Read(buf, len); }
00634 
00635     PINDEX GetLastReadCount() const
00636     { return (baseChannel == NULL) ? lastReadCount : baseChannel->GetLastReadCount(); }
00637 
00655     virtual BOOL RecordSound(
00656       PSound & sound 
00657     )
00658     { return (baseChannel == NULL) ? FALSE : baseChannel->RecordSound(sound); }
00659 
00672     virtual BOOL RecordFile(
00673       const PFilePath & file 
00674     )
00675     { return (baseChannel == NULL) ? FALSE : baseChannel->RecordFile(file); }
00676 
00683     virtual BOOL StartRecording()
00684     { return (baseChannel == NULL) ? FALSE : baseChannel->StartRecording(); }
00685 
00693     virtual BOOL IsRecordBufferFull() 
00694     { return (baseChannel == NULL) ? FALSE : baseChannel->IsRecordBufferFull(); }
00695 
00704     virtual BOOL AreAllRecordBuffersFull() 
00705     { return (baseChannel == NULL) ? FALSE : baseChannel->AreAllRecordBuffersFull(); }
00706 
00714     virtual BOOL WaitForRecordBufferFull() 
00715     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForRecordBufferFull() ; }
00716 
00725     virtual BOOL WaitForAllRecordBuffersFull() 
00726     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForAllRecordBuffersFull() ; }
00728 
00729   protected:
00730     PSoundChannel * baseChannel;
00731 };
00732 
00733 
00735 
00736 // define the sound plugin service descriptor
00737 
00738 class PSoundChannelPluginServiceDescriptor : public PPluginServiceDescriptor 
00739 {
00740   public:
00741     PSoundChannelPluginServiceDescriptor(
00742                      unsigned (*_GetVersion)(),
00743                PSoundChannel *(*_CreateInstance)(),
00744                  PStringArray (*_GetDeviceNames)(PSoundChannel::Directions)
00745      )
00746     : PPluginServiceDescriptor(_GetVersion),
00747       CreateInstance(_CreateInstance),
00748       GetDeviceNames(_GetDeviceNames)
00749     { }
00750 
00751     PSoundChannel *(*CreateInstance)();
00752     PStringArray (*GetDeviceNames) (PSoundChannel::Directions);
00753 };
00754 
00755 
00756 #define PCREATE_SOUND_SERVICE_DESCRIPTOR(className, versionFn) \
00757 PSoundChannel * className##_CreateInstance () \
00758 { \
00759   return new className; \
00760 } \
00761 \
00762 PStringArray className##_GetDeviceNames (PSoundChannel::Directions dir) \
00763 { \
00764   return className::GetDeviceNames(dir); \
00765 } \
00766 \
00767 PSoundChannelPluginServiceDescriptor className##_descriptor(\
00768    versionFn, \
00769    className##_CreateInstance, \
00770    className##_GetDeviceNames \
00771 ); \
00772 
00773 #define PCREATE_SOUND_PLUGIN(name, className) \
00774 PCREATE_PLUGIN_VERSION_FN(name, PSoundChannel) \
00775 PCREATE_SOUND_SERVICE_DESCRIPTOR(className, PPLUGIN_VERSION_FN(name, PSoundChannel)) \
00776 PCREATE_PLUGIN(name, PSoundChannel, &className##_descriptor)
00777 
00778 #endif
00779 
00780 // End Of File ///////////////////////////////////////////////////////////////

Generated on Wed Sep 28 10:27:33 2005 for PWLib by  doxygen 1.4.4