Enhancement Proposals Index, PortAudio Home Page
Updated: July 31, 2002
This proposal is sufficiently well defined to be implemented.
Currently (V18) the paHostError error code may be returned from PortAudio functions to indicate that a platform-specific error condition occurred. Clients who want to discover further information about the error must call Pa_GetHostError() to get the platform-specific error code, and then determine which host API issued the error code in order to translate the error code into a meaningful message.
The current situation is considered ambiguous and difficult to work with. Specifically, it introduces dependencies on platform-specific error systems. However, completely hiding the presence of unusual host error conditions is considered equally unsatisfactory as it makes error reporting and debugging more difficult.
Where ever practical PortAudio will convert host api error codes into meaningful PortAudio error codes. In some cases, new PortAudio error codes may be defined to accomodate this error code translation process. In the case of the pa_win_mme implementation for example, this means translating the following MME error codes:
MMSYSERR_ALLOCATED to paDeviceBusy (new) MMSYSERR_BADDEVICEID to paInvalidDeviceId (already defined) MMSYSERR_NODRIVER to paDriverMissing (new) MMSYSERR_NOMEM to paInsufficientMemory (already defined) WAVERR_BADFORMAT to paSampleFormatNotSupported (already defined)
The following new error codes have been proposed to clarify Pa_OpenStream error conditions:
paSampleRateNotSupported paNumChannelNotSupported
The existing paHostError code, and the Pa_GetHostError() function will be removed, and replaced by the mechanism described below.
A new error code paUnanticipatedHostError will be defined. When this error code is returned by a PortAudio function, additional information about the error may be obtained by calling Pa_GetLastHostErrorInfo() which will return a pointer to a PaHostErrorInfo structure as follows:
typedef struct PaHostErrorInfo{
PaHostApiTypeId hostApiType; /* the host API which returned the error code */
long errorCode; /* the error code returned */
const char *errorText; /* a textual description of the error if available, otherwise a zero-length string */
}PaHostErrorInfo;
const PaHostErrorInfo* Pa_GetLastHostErrorInfo();
The error information returned by Pa_GetLastHostError() will never be modified asyncronously by errors occurring in other PortAudio owned threads (such as the thread that manages the PortAudio callback.)
This mechanism is provided as a last resort, primarily to enhance debugging by providing clients with access to all available error information.
There will always be unanticipated circumstances when PortAudio implementations recieve error codes from the host api which were note expected. It is considered of greater practical benefit to make such unexpected error codes available to the client rather than returning a generic error code and hiding the host error code from the client.
All PortAudio API functions should be examined to ensure that clear and specific error codes are provided for all possible parameter value errors.
One reason to remove support for host error codes is that clients that want to display error text to end users in different languages will only be able to do so for standard PortAudio error codes. However, it would still be possible to construct a sensical error message when paUnanticipatedHostError is returned, such as:
An unanticipated error was encountered while using ASIO, error code 3456 : "A specific ASIO error string saying something useful."
There was some concern about polluting the PortAudio error code namespace with platform-specific error codes, and of the potential overhead of including platform specific error strings on other platforms. Another suggestion has been to add a Pa_GetHostErrorText() function.
A suggestion was made to extend Pa_GetErrorText() so that it retrieved host API specific error strings when a host error occurs, however this was deemed too complicated to implement, especially when multiple host APIs were in use simultaneously.
The possibility of extending the scope of this proposal was discussed in this thread: http://techweb.rfa.org/pipermail/portaudio/2002-January/000358.html Specifically, the removal of paHostError and Pa_GetHostError() seems to be the only way to provide a truly portable error reporting mechanism.
This proposal improves the quality of PortAudio diagnostics. Client code that depends on paHostError code or Pa_GetHostError() will need to be updated.