Error State

Most operations in DVDBuilder produce a result that tells whether the operation has succeeded or not and also gives the reason for the failure. The operation result, also called the error state is accessible through the property: Error of type ErrorInfo.

A number of interfaces use that property to expose the error state of an object.

In general the error state represents the result of the last operation performed by the object. The error state is updated after every operation.

ErrorInfo.Facility Property
Gets the source of the last error. This value is indicative about the success of the last operation. If it is ErrorFacility.Success then the last operation has fully succeeded and the values returned by Code should be ignored. Any other value than ErrorFacility.Success means that the last operation has failed in some way.

See ErrorFacility

ErrorInfo.Code Property
Returns the error code of the last operation. By itself the error code does not imply the success or the failure of the operation and should be ignored when ErrorFacility is ErrorFacility.Success. The error code should be interpreted only when the failed component (error facility) is recognized. DVDBuilder provides the error codes for the built-in error facilities: ErrorFacility.VideoRecorder, ErrorFacility.VRDevice and ErrorFacility.VRDeivicePlugin. However some errors may be generated by external components like the PrimoBurner Engine or by the operating system. In these cases additional information is required in order to interpret the error code.

Interpret the Code as	When ErrorFacility is
VideoRecorderError	ErrorFacility.VideoRecorder
VRDeviceError	ErrorFacility.VRDevice
VRDevicePluginError	ErrorFacility.VRDevicePlugin
Operating System error. Refer to the OS documentation.	ErrorFacility.SystemWindows ErrorFacility.SystemPosix ErrorFacility.SystemMacMach ErrorFacility.SystemMacOSStatus
PrimoBurner engine error. Refer to PrimoBurner documentation.	ErrorFacility.PBEngine
External component error.	A recognized external component with available documentation.

Dealing with errors in parallel video recorder operations.

A number of video recorder operations are performed concurrently (in parallel) to all attached devices. These operations are:

prepareMedia, start, startAsync, write, stop and finalizeMedia. All of these methods (with the exception of startAsync) block while the operation is executed. They return true when the operation has succeeded for all attached devices and false when any of the attached devices has failed. When a parallel operation fails with a DeviceError (VideoRecorder.error.facility == ErrorFacility.VideoRecorder and VideoRecorder.error.code == VideoRecorderError.DeviceError) the error state of each device may be obtained by using VideoRecorder.deviceError. The device error state can be analyzed by using the properties Facilty and Code as described already in this topic. When the video recorder writes to the attached devices (VideoRecorder::write) it ignores the already failed devices, therefore their error state remains unchanged in the subsequent Write calls.

A sample case of recording to several devices.

Consider that a video should be recorded concurrently to 7 devices, named d0, d1, ... and d6 for the purpose of this sample. All possible steps involved in the recording will be discussed.

1. prepareMedia - this step is optional but if used it can generate a DeviceError(described above).

Device d0 fails during this operation and the other devices succeed.

prepareMedia returns false and the DeviceError is set in the video recorder. The application enumerates the device error state and finds the failed device.

1.1. The application aborts the recording process and informs the user about the failed device. No calls to the DVDBuilder API are necessary in this case.

or

1.2. The application decides to start the recording process and only informs the user about the failed device. It is advisable to remove the failed device from the device list especially before calling the synchronous Start method. This guarantees that the video recording will start as soon as possible.

Either start() or startAsync() but the start step is mandatory.

2.1. start

Device d1 fails during this operation. So does device d0 if it is still in the device list.

2.1.1. Upon seeing the failed devices the application stops the recording by calling the stop method.

or

2.1.2. The application reports the failed devices and starts calling the write method repeatedly.

2.2. startAsync

Device d1 fails during the asynchronous start but the application finds this only in one of the subsequent write method calls. This is true for device d0 if it is still in the device list.

2.2.1. StartAsync returns false and the application aborts the recording process because there's a logical and unrecoverable error. No further calls to the DVDBuilder API are necessary in this case.

or

2.2.2. StartAsync returns true and the application starts calling the write method repeatedly.

3. write - this step is mandatory and may be called many times to record the incoming video.

Initially the video recorder uses only devices from d2 to d6.

(writing...)

Device d2 fails at some point because the DVD disc is defective.

3.1. The application stops the recording process by calling the stop method.

or

3.2. The application reports the failed devices so far (d0, d1 and d2) and continues writing.

(writing...)

Device d3 fails at some point because the DVD disc has run out of space.

The application either stops the recording or continues to record to devices d4, d5 and d6.

(writing...)

Device d4 fails at some point because the DVD disc has run out of space.

The application decides to stop the recording instead of trying to record only to d5 and d6.

4. stop - this step is mandatory whenever the start method is called or the startAsync method succeeds.

During this step the video recorder tries to stop devices d3, d4, d5 and d6. The first three devices (d0, d1 and d2) are considered unreliable because they have truly failed, not only run out of space as d3 and d4, therefore their error state remains unchanged after this step.

Device d4 fails during this step. Stop returns false and the DeviceError is set in the video recorder. The application enumerates the device error state and finds out that the only successfully recorded devices at this point are d3, d5 and d6.

5. finalizeMedia - this step should be called if no additional recording will be appended.

During this step device d5 fails. finalizeMedia returns false and the DeviceError is set in the video recorder.

The application enumerates the device error state and finds out that devices d3 and d6 have no errors and therefore are successfully finalized.

After the whole process is completed only the video content in devices d3 and d6 is guaranteed to be played back in a standalone DVD player. However the video in d3 will be shorter as it has run out of space during the recording.