# 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 ///////////////////////////////////////////////////////////////