Suspending the Video Access Server Using Bpcsusp.h

If your application is running on a broadcast client and needs to access a video device, such as a television tuner card, it must first suspend the Video Access server and cause it to release all video devices. This is necessary because the Video Access server can continuously monitor the video devices and capture background data. If your application does not suspend the server, device conflicts can arise.

If you are writing a C++ application that needs to suspend the Video Access server, the header file Bpcsusp.h can simplify the process. This header wraps the Component Object Model (COM) calls required to suspend the Video Access server into a C++ class, CBPCSuspend. Your application can use this class to suspend the server, check the server's state, and cause the server to resume work.

To request that the Video Access server suspend operation, your application should create an instance of a CBPCSuspend object. Your application can then check whether the server was successfully suspended by calling the CBPCSuspend::IsBPCSuspended function. If IsBPCSuspended returns FALSE, the server is not suspended and there are active video clients. Your application should handle this case as it does a failure indicating a busy or open device. If IsBPCSuspended returns TRUE, the server is suspended and there are no active video clients. Your application can use the video device.

When your application is done with the video device, it should release the device by destroying the CBPCSuspend object. Doing this notifies the Video Access server that it can use the video device and resume capturing background data.

Note that CBPCSuspend uses COM to acquire an object registered in the running object table by the Video Access server. If this object is not present, CBPCSuspend works on the assumption that the server is not running and that the server is not using any devices. Checking for this object saves the application from the inefficient operation of loading the server just to find out the server was not running. If the application that created the CBPCSuspend object stops unexpectedly, COM deletes the CBPCSuspend object during cleanup. This deletion frees the Video Access server to resume using video devices without requiring a system restart or other user intervention.

Note  Your application should not use the CBPCSuspend class while it is in a state in which cross-process COM calls are disallowed. For example, if your application is currently processing a call to the Microsoft® Win32® SendMessage function or a broadcast system message, any cross-process COM calls fail with an RPC_E_CANTCALLOUT_ININPUTSYNCCALL error code. If your application is in such a state when it attempts to suspend the Video Access server, the running object table can become corrupt and lock up the server.

The following example illustrates how to use Bpcsusp.h to suspend the Video Access server. Note that you must initialize COM on the thread used before creating the CBPCSuspend object. For more information about initializing COM on a thread, see the documentation for the COM functions CoInitialize and CoInitializeEx in the Platform SDK.

#include <vidsvr.h> // This header is created by compiling Vidsvr.odl.
                    // It provides CLSID_BPCSuspend and IBPCSuspended.
 
#include <bpcsusp.h> // The CBPCSuspend header file
 
#include "MyHeader.h" // ISV header file, containing declarations for 
                      // ERROR_CODE, DEVICE, ERROR_CODE values, and so 
                      // on.
 
ERROR_CODE AccessVideoDevice(DEVICE dSomeDevice)
{
  CBPCSuspend* poSuspend;
 
  // Request the Video Access server suspend and release devices.
  poSuspend = new CBPCSuspend;
 
  // Check that the object was created.
  if (poSuspend == NULL)
    return ERROR_COULD_NOT_CREATE_OBJECT;
 
  // Check that the server is suspended.
  if (poSuspend->IsBPCSuspended())
  {
    // . . . Code that uses the device
  } else {
    // . . . Code that handles the device-not-ready error
    return ERROR_COULD_NOT_SUSPEND_VIDEO_SERVER;
  }
 
  // Cause the server to resume work.
  delete poSuspend;
  return ERROR_SUCCESFUL_COMPLETION;
};