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: 28275 $
00030  * $Author: rjongbloed $
00031  * $Date: 2012-08-29 21:42:35 -0500 (Wed, 29 Aug 2012) $
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 = -1,
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     Directions GetDirection() const
00411     {
00412       return activeDirection;
00413     }
00414 
00416     static const char * GetDirectionText(Directions dir);
00417 
00418     virtual const char * GetDirectionText() const
00419     {
00420       return GetDirectionText(activeDirection);
00421     }
00422 
00430     virtual PBoolean Abort();
00432 
00444     virtual PBoolean SetFormat(
00445       unsigned numChannels = 1,     
00446       unsigned sampleRate = 8000,   
00447       unsigned bitsPerSample = 16   
00448     );
00449 
00451     virtual unsigned GetChannels() const;
00452 
00454     virtual unsigned GetSampleRate() const;
00455 
00457     virtual unsigned GetSampleSize() const;
00458 
00467     virtual PBoolean SetBuffers(
00468       PINDEX size,      
00469       PINDEX count = 2  
00470     );
00471 
00477     virtual PBoolean GetBuffers(
00478       PINDEX & size,    // Size of each buffer
00479       PINDEX & count    // Number of buffers
00480     );
00481 
00482     enum {
00483       MaxVolume = 100
00484     };
00485 
00494     virtual PBoolean SetVolume(
00495       unsigned volume   
00496     );
00497 
00506     virtual PBoolean GetVolume(
00507       unsigned & volume   
00508     );
00509 
00515     virtual bool SetMute(
00516       bool mute   
00517     );
00518 
00524     virtual bool GetMute(
00525       bool & mute   
00526     );
00527 
00529 
00532 
00553     virtual PBoolean Write(const void * buf, PINDEX len);
00554 
00555 
00578     virtual PBoolean Write(
00579       const void * buf,         
00580       PINDEX len,               
00581       const void * mark         
00582     );
00583 
00585     virtual PINDEX GetLastWriteCount() const;
00586 
00603     virtual PBoolean PlaySound(
00604       const PSound & sound,   
00605       PBoolean wait = true        
00606     );
00607 
00623     virtual PBoolean PlayFile(
00624       const PFilePath & file, 
00625       PBoolean wait = true        
00626     );
00627 
00634     virtual PBoolean HasPlayCompleted();
00635 
00642     virtual PBoolean WaitForPlayCompletion();
00643 
00645 
00676     virtual PBoolean Read(
00677       void * buf,   
00678       PINDEX len    
00679     );
00680 
00682     PINDEX GetLastReadCount() const;
00683 
00701     virtual PBoolean RecordSound(
00702       PSound & sound 
00703     );
00704 
00717     virtual PBoolean RecordFile(
00718       const PFilePath & file 
00719     );
00720 
00727     virtual PBoolean StartRecording();
00728 
00736     virtual PBoolean IsRecordBufferFull();
00737 
00746     virtual PBoolean AreAllRecordBuffersFull();
00747 
00755     virtual PBoolean WaitForRecordBufferFull();
00756 
00765     virtual PBoolean WaitForAllRecordBuffersFull();
00767 
00768   protected:
00769     PSoundChannel * m_baseChannel;
00770     PReadWriteMutex m_baseMutex;
00771 
00776     Directions      activeDirection;
00777 };
00778 
00779 
00781 
00782 // define the sound plugin service descriptor
00783 
00784 template <class className> class PSoundChannelPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00785 {
00786   public:
00787     virtual PObject *    CreateInstance(int /*userData*/) const { return new className; }
00788     virtual PStringArray GetDeviceNames(int userData) const { return className::GetDeviceNames((PSoundChannel::Directions)userData); }
00789 };
00790 
00791 #define PCREATE_SOUND_PLUGIN(name, className) \
00792   static PSoundChannelPluginServiceDescriptor<className> className##_descriptor; \
00793   PCREATE_PLUGIN(name, PSoundChannel, &className##_descriptor)
00794 
00795 #ifdef _WIN32
00796   PPLUGIN_STATIC_LOAD(WindowsMultimedia, PSoundChannel);
00797 #elif defined(__BEOS__)
00798   PPLUGIN_STATIC_LOAD(BeOS, PSoundChannel);
00799 #endif
00800 
00801 #if defined(P_DIRECTSOUND)
00802   PPLUGIN_STATIC_LOAD(DirectSound, PSoundChannel);
00803 #endif
00804 
00805 #if defined(P_WAVFILE)
00806   PPLUGIN_STATIC_LOAD(WAVFile, PSoundChannel)
00807 #endif
00808 
00809 
00810 #endif // PTLIB_SOUND_H
00811 
00812 
00813 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Feb 15 20:58:31 2013 for PTLib by  doxygen 1.4.7