PTLib  Version 2.10.4
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  * $Revision: 26804 $
00030  * $Author: rjongbloed $
00031  * $Date: 2011-12-17 01:23:10 -0600 (Sat, 17 Dec 2011) $
00032  */
00033 
00034 
00035 #ifndef PTLIB_SOUND_H
00036 #define PTLIB_SOUND_H
00037 
00038 #ifdef P_USE_PRAGMA
00039 #pragma interface
00040 #endif
00041 
00042 #include <ptlib/plugin.h>
00043 #include <ptlib/pluginmgr.h>
00044 
00052 class PSound : public PBYTEArray
00053 {
00054   PCLASSINFO(PSound, PBYTEArray);
00055 
00056   public:
00065     PSound(
00066       unsigned numChannels = 1,    
00067       unsigned sampleRate = 8000,  
00068       unsigned bitsPerSample = 16, 
00069       PINDEX   bufferSize = 0,     
00070       const BYTE * data = NULL     
00071     );
00072 
00075     PSound(
00076       const PFilePath & filename   
00077     );
00078 
00081     PSound & operator=(
00082       const PBYTEArray & data  
00083     );
00085 
00097     PBoolean Load(
00098       const PFilePath & filename   
00099     );
00100 
00107     PBoolean Save(
00108       const PFilePath & filename   
00109     );
00111 
00114 
00115     PBoolean Play();
00116 
00118     PBoolean Play(const PString & device);
00119 
00123     void SetFormat(
00124       unsigned numChannels,   
00125       unsigned sampleRate,    
00126       unsigned bitsPerSample  
00127     );
00128 
00132     unsigned GetEncoding()   const { return encoding; }
00133 
00135     unsigned GetChannels()   const { return numChannels; }
00136 
00138     unsigned GetSampleRate() const { return sampleRate; }
00139 
00141     unsigned GetSampleSize() const { return sampleSize; }
00142 
00144     DWORD    GetErrorCode()  const { return dwLastError; }
00145 
00147     PINDEX   GetFormatInfoSize()  const { return formatInfo.GetSize(); }
00148 
00150     const void * GetFormatInfoData() const { return (const BYTE *)formatInfo; }
00152 
00163     static PBoolean PlayFile(
00164       const PFilePath & file, 
00165       PBoolean wait = true        
00166     );
00167 
00169     static void Beep();
00171 
00172   protected:
00174     unsigned   encoding;      
00176     unsigned   numChannels;   
00178     unsigned   sampleRate;    
00180     unsigned   sampleSize;    
00182     DWORD      dwLastError;   
00184     PBYTEArray formatInfo;    
00185 };
00186 
00187 
00251 class PSoundChannel : public PChannel
00252 {
00253   PCLASSINFO(PSoundChannel, PChannel);
00254 
00255   public:
00258     enum Directions {
00259       Closed,
00260       Recorder,
00261       Player
00262     };
00263 
00265     PSoundChannel();
00266 
00270     PSoundChannel(
00271       const PString & device,       
00272       Directions dir,               
00273       unsigned numChannels = 1,     
00274       unsigned sampleRate = 8000,   
00275       unsigned bitsPerSample = 16   
00276     );
00277     // 
00278 
00279     virtual ~PSoundChannel();
00280     // Destroy and close the sound driver
00282 
00287     static PStringArray GetDriverNames(
00288       PPluginManager * pluginMgr = NULL   
00289     );
00290 
00295     static PStringArray GetDriversDeviceNames(
00296       const PString & driverName,         
00297       Directions direction,               
00298       PPluginManager * pluginMgr = NULL   
00299     );
00300 
00301     // For backward compatibility
00302     static inline PStringArray GetDeviceNames(
00303       const PString & driverName,
00304       Directions direction,
00305       PPluginManager * pluginMgr = NULL
00306     ) { return GetDriversDeviceNames(driverName, direction, pluginMgr); }
00307 
00310     static PSoundChannel * CreateChannel (
00311       const PString & driverName,         
00312       PPluginManager * pluginMgr = NULL   
00313     );
00314 
00315     /* Create the matching sound channel that corresponds to the device name.
00316        So, for "fake" return a device that will generate fake video.
00317        For "Phillips 680 webcam" (eg) will return appropriate grabber.
00318        Note that Phillips will return the appropriate grabber also.
00319 
00320        This is typically used with the return values from GetDeviceNames().
00321      */
00322     static PSoundChannel * CreateChannelByName(
00323       const PString & deviceName,         
00324       Directions direction,               
00325       PPluginManager * pluginMgr = NULL   
00326     );
00327 
00333     static PSoundChannel * CreateOpenedChannel(
00334       const PString & driverName,         
00335       const PString & deviceName,         
00336       Directions direction,               
00337       unsigned numChannels = 1,           
00338       unsigned sampleRate = 8000,         
00339       unsigned bitsPerSample = 16,        
00340       PPluginManager * pluginMgr = NULL   
00341     );
00342 
00351     static PString GetDefaultDevice(
00352       Directions dir    // Sound I/O direction
00353     );
00354 
00367     static PStringArray GetDeviceNames(
00368       Directions direction,               
00369       PPluginManager * pluginMgr = NULL   
00370     );
00371 
00378     virtual PBoolean Open(
00379       const PString & device,       
00380       Directions dir,               
00381       unsigned numChannels = 1,     
00382       unsigned sampleRate = 8000,   
00383       unsigned bitsPerSample = 16   
00384     );
00385 
00391     virtual PBoolean IsOpen() const;
00392 
00397     virtual PBoolean Close();
00398 
00404     virtual int GetHandle() const;
00405 
00407     virtual PString GetName() const;
00408 
00410     virtual Directions GetDirection() const
00411     {
00412       return activeDirection;
00413     }
00414 
00416     static const char * GetDirectionText(Directions dir)
00417     {
00418       return (dir == Player)? "Playback" : ((dir == Recorder)? "Recording" : "Closed");
00419     }
00420 
00421     virtual const char * GetDirectionText() const
00422     {
00423       return GetDirectionText(activeDirection);
00424     }
00425 
00433     virtual PBoolean Abort();
00435 
00447     virtual PBoolean SetFormat(
00448       unsigned numChannels = 1,     
00449       unsigned sampleRate = 8000,   
00450       unsigned bitsPerSample = 16   
00451     );
00452 
00454     virtual unsigned GetChannels() const;
00455 
00457     virtual unsigned GetSampleRate() const;
00458 
00460     virtual unsigned GetSampleSize() const;
00461 
00470     virtual PBoolean SetBuffers(
00471       PINDEX size,      
00472       PINDEX count = 2  
00473     );
00474 
00480     virtual PBoolean GetBuffers(
00481       PINDEX & size,    // Size of each buffer
00482       PINDEX & count    // Number of buffers
00483     );
00484 
00485     enum {
00486       MaxVolume = 100
00487     };
00488 
00497     virtual PBoolean SetVolume(
00498       unsigned volume   
00499     );
00500 
00509     virtual PBoolean GetVolume(
00510       unsigned & volume   
00511     );
00513 
00516 
00537     virtual PBoolean Write(const void * buf, PINDEX len);
00538 
00539 
00562     virtual PBoolean Write(
00563       const void * buf,         
00564       PINDEX len,               
00565       const void * mark         
00566     );
00567 
00569     virtual PINDEX GetLastWriteCount() const;
00570 
00587     virtual PBoolean PlaySound(
00588       const PSound & sound,   
00589       PBoolean wait = true        
00590     );
00591 
00607     virtual PBoolean PlayFile(
00608       const PFilePath & file, 
00609       PBoolean wait = true        
00610     );
00611 
00618     virtual PBoolean HasPlayCompleted();
00619 
00626     virtual PBoolean WaitForPlayCompletion();
00627 
00629 
00660     virtual PBoolean Read(
00661       void * buf,   
00662       PINDEX len    
00663     );
00664 
00666     PINDEX GetLastReadCount() const;
00667 
00685     virtual PBoolean RecordSound(
00686       PSound & sound 
00687     );
00688 
00701     virtual PBoolean RecordFile(
00702       const PFilePath & file 
00703     );
00704 
00711     virtual PBoolean StartRecording();
00712 
00720     virtual PBoolean IsRecordBufferFull();
00721 
00730     virtual PBoolean AreAllRecordBuffersFull();
00731 
00739     virtual PBoolean WaitForRecordBufferFull();
00740 
00749     virtual PBoolean WaitForAllRecordBuffersFull();
00751 
00752   protected:
00753     PSoundChannel * baseChannel;
00754 
00759     Directions      activeDirection;
00760 };
00761 
00762 
00764 
00765 // define the sound plugin service descriptor
00766 
00767 template <class className> class PSoundChannelPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00768 {
00769   public:
00770     virtual PObject *    CreateInstance(int /*userData*/) const { return new className; }
00771     virtual PStringArray GetDeviceNames(int userData) const { return className::GetDeviceNames((PSoundChannel::Directions)userData); }
00772 };
00773 
00774 #define PCREATE_SOUND_PLUGIN(name, className) \
00775   static PSoundChannelPluginServiceDescriptor<className> className##_descriptor; \
00776   PCREATE_PLUGIN(name, PSoundChannel, &className##_descriptor)
00777 
00778 #ifdef _WIN32
00779   PPLUGIN_STATIC_LOAD(WindowsMultimedia, PSoundChannel);
00780 #elif defined(__BEOS__)
00781   PPLUGIN_STATIC_LOAD(BeOS, PSoundChannel);
00782 #endif
00783 
00784 #if defined(P_DIRECTSOUND)
00785   PPLUGIN_STATIC_LOAD(DirectSound, PSoundChannel);
00786 #endif
00787 
00788 #if defined(P_WAVFILE)
00789   PPLUGIN_STATIC_LOAD(WAVFile, PSoundChannel)
00790 #endif
00791 
00792 
00793 #endif // PTLIB_SOUND_H
00794 
00795 
00796 // End Of File ///////////////////////////////////////////////////////////////
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines