Introduction
By using the GeViScope registry (GSCREGISTRY) it is possible to modify GeViScope/Re_porter settings programmatically. The GscRegistry is a proprietary registry format developed by GEUTEBRÜCK. This registry format is similar to the Microsoft Windows registry.
All needed GeViScope server settings are stored in the GscRegistry database. The creation of own registry databases based on files is also possible.
The GEUTEBRÜCK GEVISCOPE SDK provides several classes and methods to allow a comfortable access to the GscRegistry.
Requirements
The following requirements are needed to create a .NET application that uses the GscRegistry functionality:
• .NET-Framework 2.0 SP1 or newer
- .NET-Framework 2.0 SP1 Wrapper-Assemblies:
GscExceptionsNET_2_0.dll
GscDBINET_2_0.dll
- .NET-Framework 4.0 Wrapper-Assemblies:
GscExceptionsNET_4_0.dll
GscDBINET_4_0.dll
• Native Win32-DLLs, used by the .NET-Wrapper:
- GscActions.dll
- GscDBI.dll
- GscMediaPlayer.dll
- GscHelper.dll
- MscDBI.dll
• Microsoft Visual C++ Redistributable Package
Using the registry
In the following, the usage of the GscRegistry with .NET is explained in detail. It discusses the following steps:
All necessary classes and methods for using the GscRegistry are available in the GscDBI namespace. To include this namespace the following using-statement is needed:
using GEUTEBRUECK.GeViScope.Wrapper.DBI;
Open the registry
To read or modify GeViScope/Re_porter settings it is necessary to establish a connection to the preferred GeViScope/Re_porter server before. After this is done you need to create a new object of the class GscRegistry and initialize it by using the CreateRegistry() method which is contained in the GscServer object.
C#-Code: Open the registry
if (_GscServer != null)
{
// create an object instance of the server registry
GscRegistry GscRegistry = _GscServer.CreateRegistry();
if (GscRegistry != null)
{
// define an array for the setup read request (registry node paths to read)
GscRegistryReadRequest[] ReadRequests = new GscRegistryReadRequest[1];
ReadRequests[0] = new GscRegistryReadRequest("/", 0);
// read the nodes (setup data) out of the server registry
GscRegistry.ReadNodes(ReadRequests);
}
}
The method ReadNodes() of the GscRegistry object expects an array of the type GscRegistryReadRequest which contains all node paths to be read out of the registry. In the source code snippet above, the array simply contains one element which represents the root node (“/”). By reading the root node the entire registry will be read out.
Read values of nodes
The following source code snippet shows how to read values out of nodes:
C#-Code: Read values out of nodes
if (GscRegistry != null)
{
GscRegNode RegNode = GscRegistry.FindNode("/System/MediaChannels/");
for (int i = 0; i < RegNode.SubNodeCount; ++i)
{
// find the GeViScope registry node of the parent node by means of the index
GscRegNode SubRegNode = RegNode.SubNodeByIndex(i);
GscRegVariant RegVariant = new GscRegVariant();
// Get the value "Name" out of the sub registry type and store the value and
// value type in the GscRegVariant class
SubRegNode.GetValueInfoByName("Name", ref RegVariant);
if (RegVariant != null && RegVariant.ValueType == GscNodeType.ntWideString)
Console.WriteLine(RegVariant.Value.WideStringValue);
}
}
To read a specific node out of the registry the GscRegistry class provides the method FindNode().
For that the path to the preferred node has to be committed to the method and it you will get back an object of the type of GscRegNode. This object contains all sub nodes and values of the found node.
To access a sub node of the parent node the method SubNodeByIndex() provided by the class GscRegNode can be used or use the SubNodeByName() method if the name of the sub node is already known.
The method GetValueInfoByName() can be used to access a specific value of a node. This method expects the name of the specific value as well as a reference to an object of type of GscRegVariant. The GscRegVariant object will be filled with the type of the value (ValueType) as well as the value itself (Value).
Create a node
To create a new node in a parent node the method CreateSubNode() which is provided by the class GscRegNode needs to be called. The method expects the name of the new node.
C#-Code: Create a node
if (_GscRegistry != null)
{
GscRegNode RegNode = _GscRegistry.FindNode("/System/MediaChannels/0000");
// create a new sub node in NodePath
if (RegNode != null)
RegNode.CreateSubNode("NewNode");
}
Add values to a node
There are several methods in the class GscRegNode to add values to a node. Depending on the type of the value it is needed to call the right method for writing this type into the registry. For example if you would like to write an Int32 value into the registry you need to use the method WriteInt32().
C#-Code: Add values to node
public void AddValue(string NodePath, string ValueName, GscNodeType ValueType,
object Value)
{
GscRegNode RegNode = _GscRegistry.FindNode(NodePath);
if (RegNode != null)
{
switch (ValueType)
{
case GscNodeType.ntWideString:
{
RegNode.WriteWideString(ValueName, Value.ToString());
break;
}
case GscNodeType.ntInt32:
{
RegNode.WriteInt32(ValueName, Convert.ToInt32(Value));
break;
}
}
}
}
Save the registry
After the GscRegistry object was modified (e.g. new nodes/new values), the server also needs to know about the changes made. For this the GscRegistry class provides the method WriteNodes().
C#-Code: Add values to node
// define an array for the setup write request
GscRegistryWriteRequest[] WriteRequests = new GscRegistryWriteRequest[1];
WriteRequests[0] = new GscRegistryWriteRequest("/", 0);
GscRegistry.WriteNodes(WriteRequests, true);
The WriteNodes() method expects an array containing objects of the type of GscRegistryWriteRequest. Each GscRegistryWriteRequest contains a path to a node that has to be saved.
NOTICE
It is recommended to only add one element to this array which contains the root path (“/”). This results in saving the entire registry structure.
Structure of GSCRegistry
The GEVISCOPE SDK offers two possibilities to browse the structure of the GscRegistry. By means of the application GscRegEdit that is delivered with the SDK, it is possible to browse or modify the registry similar to Microsoft’s Windows registry.
In addition to GscRegEdit you can also use the registry editor which is integrated in GSCSetup. To activate this feature the key combination STRG+ALT+U needs to be actuated. The entry Registry editor in the section Utilities in the navigation bar on the left will now be shown.
Examples
To get a better idea of how to use the GscRegistry, the GEVISCOPE SDK provides further .NET example applications.
The examples can be found in the folder „Examples“ folder in the GeViScopeSDK main folder: