From: Ross Bencina <rossb@audiomulch.com>
Date: Fri, 2 Sep 2016 09:27:47 +0000 (+1000)
Subject: hotplug: rename Pa_UpdateAvailableDeviceList() to Pa_RefreshDeviceList(). Clean up... 
X-Git-Url: https://andrewgundersen.net/repos?a=commitdiff_plain;h=3f7c315f2299bee65e4f0e852606c84812423a12;p=portaudio

hotplug: rename Pa_UpdateAvailableDeviceList() to Pa_RefreshDeviceList(). Clean up doc comment for Pa_RefreshDeviceList().
---

diff --git a/include/portaudio.h b/include/portaudio.h
index 09d6aa8..407feb3 100644
--- a/include/portaudio.h
+++ b/include/portaudio.h
@@ -439,19 +439,24 @@ PaDeviceIndex Pa_GetDefaultInputDevice( void );
 */
 PaDeviceIndex Pa_GetDefaultOutputDevice( void );
 
-/** Update the list of available devices to match currently available hardware devices.
+/** Refresh the list devices to match currently available hardware devices.
 
- PortAudio's list of available devices is usually frozen at the time Pa_Initialize() is 
- called. Pa_UpdateAvailableDeviceList() may be called to refresh PortAudio's list
- of available devices at any time while PortAudio is initialized.
+ PortAudio's list of devices is usually frozen when Pa_Initialize() is
+ called. Call Pa_RefreshDeviceList() to refresh PortAudio's device list
+ at any time while PortAudio is initialized.
 
- @note Open streams will not be affected by calls to this function, but
- any previously returned PaDeviceInfo pointers are invalidated once this
- function is called.
+ @return an error code indicating whether the refresh was successful.
 
- @return an error code indicating whether the device refresh was successful.
+ If the function succeeds, future calls to Pa_GetDeviceCount() may return
+ a different count than before, all device indexes may refer to
+ different devices, and any previously returned PaDeviceInfo pointers are
+ invalidated.
+
+ If the function fails, the device list is unchanged.
+
+ @note Open streams will not be affected by calls to this function.
  */
-PaError Pa_UpdateAvailableDeviceList( void );
+PaError Pa_RefreshDeviceList( void );
 
 
 /** The type used to represent monotonic time in seconds. PaTime is 
diff --git a/src/common/pa_front.c b/src/common/pa_front.c
index f530bd9..def07e3 100644
--- a/src/common/pa_front.c
+++ b/src/common/pa_front.c
@@ -755,7 +755,7 @@ PaDeviceIndex Pa_GetDefaultOutputDevice( void )
 }
 
 
-PaError Pa_UpdateAvailableDeviceList( void )
+PaError Pa_RefreshDeviceList( void )
 {
     PaError result     = paNoError;
     void **scanResults = NULL;
diff --git a/test/patest_update_available_device_list.c b/test/patest_refresh_device_list.c
similarity index 95%
rename from test/patest_update_available_device_list.c
rename to test/patest_refresh_device_list.c
index 2c077f5..69adae9 100644
--- a/test/patest_update_available_device_list.c
+++ b/test/patest_refresh_device_list.c
@@ -38,7 +38,7 @@ int main(int argc, char* argv[])
         if( getchar() == 'q' )
             break;
 
-        Pa_UpdateAvailableDeviceList();
+        Pa_RefreshDeviceList();
     }
 
     Pa_Terminate();