Using TestPoints in VideoClick

Contents

Introduction

Requirements from test points

Architecture of the implemented system

Using a test point

Adding a test point to the system

Creating new test point types

Code documentation

Examples


What is a testpoint?

A testpoint is a point in the data flow of a system ( in our case, VideoClick), where data can be dumped for analysis.

The data dumped can be an exact copy of the data in the system, or it can be any filtered information derived from this data.

<< example of sink filter with and without tespoint filter >>

 

What do we require of a test point?

Architecture of the TP

After years of thought, we came up with two major entities: TestPoint Manager and TestPoint handler.
The TpManager is responsible for answering if a given TP is active and supply an object that will handle the data  written to the TP ( in other words, it is a class factory, giving the caller an object ( the handler )).
The TestPoint Handler can handle limited types of test points: e.g. a handler for IDataSink.
( A single handler may handle more than one type of TP).

Each TestPoint handler implements an inteface known to the TPManager, through which the TPManger helps the handler to initilize itself ( the example will clarify this).
It is important that the TPManger knows about the handler only that it implements ITestPoint interface.
This seperation enables us to grow the system ( add handlers and handlers functionality) without touching the manager.

The handler is responsible to read relevant configuration information for the specific testpoint.
For example, there might be two TP in the system, both dumping data to IDataSink2 interface.
At the first TP, the ouput should go to C:\tmp\recServerOutput.mpg and the second TP should go through a socket to some other machine.
Again, it is only the handler that knows this - the manager knows which handler takes care of a particular testpoint, and the client code only knows it has an IDataSink2 at hand.

Using a test point

(This paragraph is not only for developers)

Before using a test point, you have to know its GUID, or the easier task - know its name.
Open the Registry at HKEY_LOCAL_MACHINE\Software\Vsoft\TestPoints and find the needed key:

Registry.gif (9196 bytes)

Now, you can turn the test point ON or OFF by setting the "IsActive" to 1 or 0:

ModifyRegValue.gif (3212 bytes)

You may change other parameters as well, e.g. the dump file name.

Remember: When you no longer need the test point, turn it OFF !

 

Implmentation of the TP framework

The above architecture is implmented by a COM server - the TPManager, and a set of handlers - each of them a COM object.

The test point configuration data is stored in the registry under HKLM\Software\Vsoft\TestPoint.

Data format for the TPs:

Each TP has GUID ( do not confuse with the handler's ). a TP's GUID is a subkey under HKLM\Software\Vsoft\TestPoints .
Under each such subkey there are 3 values:
String: "NAME"  -  user friendly name of this TP

Any other values are for the use of the handler and are defined for each handler seperatly. Some Examples might be:

STRING:"File" - name of the dump file ( PID and TID will be appended before the extension)

Currently available testpoint handlers

Description ProgId Interfaces exposed Date published
Simple IDataSink2 dumping Vsoft.DataSinkHandler IDataSink2
IDataSinkWithReset
9 Aug 1999
Packetized data dumping Vsoft.PacketizedDataSinkHandler IPacketizedDataSink 1 Sep 1999

The existing TP handlers are not good for me. How do I create new one?

Your handler may be Inproc or Outproc COM server. Currently (Aug 1999) we have dreams for future services supported by handlers, but today, you have to implement ITestPoint only.
The manager asks for IUnknown from the newly created handler, and later on the client asks for the actual interface needed for the testpoint. This is where your INewAndBetterTp is used.

A good starting point is to copy portions from an existing handler.

Don't forget to create a header file for your new handler. The contents of this file is the documentation of your handler and it is used by any testpoint that uses your hander.
Location of this header file is in VideoClick2.1/interface/h/TestPoints/handlers
See the example file for the required content of the header file.

Interface and class documentation

class documentation was created using BumbleBee.


Sinppet of a sample code ( file : TpTester.cpp ). See also another example

#include "ITestPoint.h"
#include "stdio.h"
#include "FileObj.h"
#include "SourceTestPoint.h"

// {BCB9DFB3-406F-11d3-AEF9-000000000000}
static const GUID MyFirstTp1 =
{ 0xbcb9dfb3, 0x406f, 0x11d3, { 0xae, 0xf9, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 } };

int main(int ac, char ** av)
{
...
   // {{connect the TP if needed
    IDataSource * pSource = NULL;
    SourceTestPoint srcTp;
    hr = srcTp.Connect(MyFirstTp1, &aSource, &pSource);
    if(S_OK != hr)
    {
        // no need for any other action, since the connection is made anyway
    }
    // TestPoint handling}}
...
}


Last Edited: 9 September 1999. Send mail to Noam Cohen