Error Handling

Each function of PVCAM API with the exception of pl_error_code returns either PV_OK or PV_FAIL depending on the outcome of the function call. If the call is successful, the function will return PV_OK and if the call is unsuccessful, PV_FAIL will be returned.

Available Functions

• pl_error_code - returns the error code for the last API call. This is the only PVCAM API function that does not return PV_OK or PV_FAIL values.
• pl_error_message - provides the error message for a given error code. This is the only PVCAM API function that does not alter error code on failure.

Both functions work before pl_pvcam_init is called. This allows an error message to be returned if pl_pvcam_init fails.

If a PVCAM function call fails, PVCAM generates an error code with a message describing the error. The message may contain a dynamic part with extra details if a platform-specific call or a call to driver layer fails. Please, bear in mind that each PVCAM function call resets the error code. As a consequence, if a call fails and another function is called before retrieving the error code, the previous error code will be lost. This also applies to dynamic part of the error message with additional details.

Accessing PVCAM API from multiple threads

When PVCAM is accessed from multiple threads simultaneously, it is recommended to lock the PVCAM API calls and error code retrieval function with a mutex as in the following example. This ensures that the error code is not reset by another call to PVCAM API from a different thread.

bool PvcamWrapperClass::StartAcquisition()
{
    // Ensure that access to PVCAM is synchronized
    std::lock_guard<std::mutex> lock(m_pvcamApiMutex);

    if (PV_OK != pl_exp_start_seq(hcam, pPixelBuffer))
    {
        const int16 errorCode = pl_error_code();
        char errorMessage[ERROR_MSG_LEN];
        pl_error_message(errorCode, errorMessage);
        // throw error, log error, etc...
        return false;
    }
    return true; // Acquisition is running
}